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Preface 



This manual consists of a section that introduces the system calls followed by sections that 
describe a separate operating system manager (e.g., the process manager, stream manager, and 
variable formatting package). The sections that describe the managers are in alphabetical 
order by manager name and consist of a description of the data types used by the manager, 
the syntax of the manager's programming calls, and the error messages generated by the 
manager. Each section is preceded by its own table of contents. 

For easy organization, we have numbered the pages of by system manager. For example, the 
third page in the ACLM section is page ACLM-3. 

You should use this manual with the programming handbooks listed under Related Documents . 
These programming handbooks give detailed instructions about using the programming calls. 

Audience 

This manual is intended for programmers who are writing application programs using DOMAIN 
system calls. Readers of this manual should be familiar with FORTRAN, Pascal, or C and the 
operating system as described in the DOMAIN System User's Guide. This manual is not 
intended as a tutorial document, but as a reference for programmers who need to use operating 
system services. 

Summary of Technical Changes 

This manual has been reduced in size from two volumes to one. The GM and GPR programming 
calls, which were previously documented here, are now documented separately. For GM calls, 
refer to DOMAIN 2D Graphics Metafile Resource Call Reference, order no. 009793; for GPR 
calls, refer to DOMAIN Graphics Primitive Routines Gall Reference, order no. 007194. 

In support of SR 9.5, the following new managers have been added: 

CTM 
FPP 
PRF 

In addition, the following calls have been added to existing managers: 

MBX_$TIMED_OPEN 

MS_$ADDMAP 

MS_$CRTEMP 

MS_$FW_PARTIAL 

MS_$MK_PERMANENT 

MS_$MK_TEMPORARY 

MS_$NEIGHBORS 

PAD_$FORCE_PROMPT 

PAD $IS ICON 
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Related Documents 

The Programming With General System Calls handbook, order no. 005506, documents how to 
write programs that use standard DOMAIN system calls including the ACLM, CAL, EC2, 
ERROR, MTS, NAME, PAD, PBUFS, PFM, PGM, PM, PROC1, PROC2, RWS, SIO, STREAM, 
TIME, TONE, TPAD, and VFMT calls. 

The Programming With System Calls for Interprocess Communication handbook, order no. 
005696, documents how to write programs that use the DOMAIN interprocess facilities including 
the MBX, MS, IPC, MUTEX, and EC2 calls. 

Documentation Conventions 

Unless otherwise noted in the text, this manual uses the following symbolic conventions. 

UPPERCASE Uppercase words or characters in formats and command 

descriptions represent keywords that you must use literally. 

lowercase Lowercase words or characters in formats and command 

descriptions represent values that you must supply. 

[ ] Square brackets enclose optional items. 

< > Braces enclose a list from which you must choose an item. 
I A vertical bar separates items in a list of choices. 

< > Angle brackets enclose the name of a key on the keyboard. 

CTRL/Z The notation CTRL/ followed by the name of a key indicates 

a control character sequence. Hold down <CTRL> while you 
type the character. 

Horizontal ellipsis points indicate that you can repeat 
the preceding item one or more times. 

Vertical ellipsis points mean that we have omitted 
irrelevant parts of a figure or example. 



Problems, Questions, and Suggestions 

We appreciate comments from the people who use our system. In order to make it easy for you 
to communicate with us, we provide the User Change Request (UCR) system for software-related 
comments, and the Reader's Response form for documentation comments. By using these formal 
channels, you make it easy for us to respond to your comments. 

You can get more information about how to submit a UCR by consulting the DOMAIN System 
Command Reference manual. Refer to the CRUCR (Create User Change Request) Shell 
command description. You can view the same description on-line by typing: 

$ HELP CRUCR <RETURN> 

For documentation comments, a Reader's Response form is located at the back of each mnmial. 
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Introduction 



This introductory section describes the DOMAIN system insert files and the format of the 
information found in the sections that follow. Each of these sections consists of a description of 
the data types used by a system manager, the syntax of the manager's programming calls, and 
the error messages generated by the system manager. We have arranged the sections of this 
manual alphabetically, by system manager name. 



DOMAIN Insert Files 

The DOMAIN system provides insert files that define data types, constants, values, and routine 
declarations. The insert files also define the exact form of each system call or routine. (Even the 
FORTRAN version does this using comments, although the FORTRAN compiler doesn't check 
the forms that you use.) 

The DOMAIN system routines are divided, by function, into several subsystems. Each subsystem 
is controlled by a system manager. The routines of each subsystem are prefixed for easy 
indentification. A subsystem prefix consists of a number of identifying characters followed by the 
special underscore and dollar-sign characters, "_$." For example, the routines that perform 
stream functions are prefixed with STREAM_$. These subsystem prefixes are also used to 
distinguish DOMAIN data types and constants that are used by the subsystem routines. 

Insert files are located in the directory /SYS/INS/. There is one insert file per subsystem for 
each programming language. Include the appropriate insert file for your programming language. 
For example, if you are using error routines in a Pascal program, you include the insert file, 
/SYS/INS/ERROR.INS.PAS. Using the same routines in a FORTRAN program, you include 
/SYS/INS/ERROR.INS.FTN. All insert files are specified using the syntax 

/SYS/INS/subsystem-prefix.INS.language- abbreviation 

where the language abbreviation is PAS (Pascal), FTN (FORTRAN), or C (C). The listing on 
the next page shows all the available insert files. 

In addition to including required subsystem insert files in a program, you must always include the 
BASE insert file for your programming language. You specify BASE insert files using the syntax 

/SYS/INS/BASE.INS.language-abbreviation 
These files contain some basic definitions that a number of subsystem routines use. 
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Summary of Insert Files 



Insert File 


Operating System Component 


/SYS/ INS/BASE . INS . Ian 


Base definitions — must always be included 


/SYS/INS/ACLM. INS . Ian 


Access control list manager 


/SYS/INS/CAL . INS . Ian 


Calendar 


/SYS/INS/CTM . INS . Ian 


Color Table Manager 


/SYS/ INS/ERROR . INS . Ian 


Error reporting 


/SYS/INS/EC2 . INS . Ian 


Eventcount 


/SYS/INS/FPP . INS . Ian 


Floating Point Package 


/SYS/INS/GMF . INS . Ian 


Graphics Map Files 


/SYS/INS/GPR . INS . Ian 


Graphics Primitives 


/SYS/INS/IOS . INS . Ian 


I/O Switch Manager 


/SYS/INS/IOS_DIR . INS . Ian 


I/O Switch Directory 


/SYS/INS/IPC . INS . Ian 


Interprocess communications datagrams 


/SYS/INS/KBD . INS . Ian 


[Useful constants for keyboard keys] 


/SYS/INS/MBX . INS . Ian 


Mailbox manager 


/SYS/INS/MS . INS . Ian 


Mapping server 


/SYS/INS/MTS . INS . Ian 


Magtape/streams interface 


/SYS/INS/MUTEX . INS . Ian 


Mutual exclusion lock manager 


/SYS/ INS/NAME . INS . Ian 


Naming server 


/SYS/ INS/PAD . INS . Ian 


Display Manager 


/SYS/INS/PBUFS . INS . Ian 


Paste buffer manager 


/SYS/INS/PFM . INS . Ian 


Process fault manager 


/SYS/ INS/PGM . INS . Ian 


Program manager 


/SYS/INS/PM . INS . Ian 


User process routines 


/SYS/INS/PRF . INS .PAS 


Print File Manager 


/SYS/INS/PR0C1 . INS . PAS 


Process manager (Pascal only) 


/SYS/INS/PR0C2 . INS . Ian 


User process manager 


/SYS/INS/RWS . INS . Ian 


Read/write storage manager 


/SYS/INS/SIO . INS . Ian 


Serial I/O 


/SYS/INS/SMD . INS . Ian 


Display driver 


/SYS/ INS/STREAMS . INS . Ian 


Stream manager 


/SYS/INS/TIME . INS . Ian 


Time 


/SYS/ INS/TONE. Ian 


Speaker 


/SYS/INS/TPAD . INS . Ian 


Touchpad manager 


/SYS/INS/VEC . INS . Ian 


Vector arithmetic 


/SYS/INS/VFMT . INS . Ian 


Variable formatter 



The suffix ".Ian" varies with the high-level language that you're using; it is either ".FTN", 
".PAS", or ".C". 



Organizational Information 

This introductory section is followed by sections for each subsystem. The material for each 
subsystem is organized into the following three parts: 

1. Detailed data type information (including illustrations of records for the use of 
FORTRAN programmers). 

2. Full description of each system call. 

3. List of possible error messages. 
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Data Type Sections 

A subsystem's data type section precedes the subsystem's individual call descriptions. Each data 
type section describes the predefined constants and data types for a subsystem. These 
descriptions include an atomic data type translation (i.e., TIME_$REL_ABS_T = 4-byte 
integer) for use by FORTRAN programmers, as well as a brief description of the type's purpose. 
Where applicable, any predefined values associated with the type are listed and described. 
Following is an example of a data type description for the TIME_$REL_ABS_T type: 



O 



TIME $REL ABS T 



A 2-byte integer. Indicator of type of time. One of 
the following predefined values: 

TIME_$RELATIVE 
Relative time. 

TIME_$ABSOLUTE 
Absolute time. 



o 



In addition, the record data types are illustrated in detail. Primarily, we have geared these 
illustrations to FORTRAN programmers who need to construct record-like structures, but we've 
designed the illustrations to convey as much information as possible for all programmers. Each 
record type illustration: 

o Shows FORTRAN programmers the structure of the record that they must construct 
using standard FORTRAN data type statements. The illustrations show the size and 
type of each field. 



o 



Describes the fields that make up the record. 



Lists the byte 
individually. 



offsets for each field. These offsets are used to access fields 



Indicates whether any fields of the record are, in turn, predefined records. 
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The following is the description and illustration of the CAL _$ TIMED ATE _REC_T predefined 
record: 



CAL $TIMEDATE REC T 



predefined 
type 



byte: 
offset 




2 
4 
6 
8 
10 



Readable time format. The 
diagram below illustrates the 
CAL_$TIMEDATE_REC_T data type 





field name 


integer 


year 


integer 


month 


integer 


day 


integer 


hour 


integer 


minute 


integer 


second 


Field 
yea 
Int 


Description: 
r 
eger representing the year 



month 

Integer representing the month. 

day 

Integer representing the day. 

hour 

Integer representing the hour 

(24 hr . format) . 

minute 

Integer representing the minute . 

second 

Integer representing the second. 



FORTRAN programmers should note that a Pascal variant record is a record structure that may 
be interpreted differently depending on usage. In the case of variant records, as many 
illustrations will appear as are necessary to show the number of interpretations. 
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System Call Descriptions 

We have listed the system call descriptions alphabetically for quick reference. Each system call 
description contains: 

• An abstract of the call's function. 

• The order of call parameters. 

• A brief description of each parameter. 

• A description of the call's function and use. 

These descriptions are standardized to make referencing the material as quick as possible. 

Each parameter description begins with a phrase describing the parameter. If the parameter can 
be declared using a predefined data type, the descriptive phrase is followed by the phrase ",in 
XXX format" where XXX is the predefined data type. Pascal or C programmers, look for this 
phrase to determine how to declare a parameter. 

FORTRAN programmers, use the second sentence of each parameter description for the same 
purpose. The second sentence describes the data type in atomic terms that you can use, such as 
"This is a 2-byte integer." In complex cases, FORTRAN programmers are referenced to the 
respective subsystem's data type section. 

The rest of a parameter description describes the use of the parameter and the values it may 
hold. 

The following is an example of a parameter description: 

access 

New access mode, in MS_$ACC_MODE_T format. This is a 2-byte integer. 
Specify only one of the following predefined values: 

MS_$R Read access . 

MS_$WR Read and write access. 

MS_$RIW Read with intent to write . 

An object which is locked MS_$RIW may not be changed to MS_$R. 



Error Sections 

Each error section lists the status codes that may be returned by subsystem calls. The following 
information appears for each error: 

• Predefined constant for the status code. 

• Text associated with the error. 
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Table of Contents 



ACLM_$DOWN ACLM-2 
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ACLM 



The ACLM (Access Control List Manager) programming calls control the protected subsystem 
privilege level. This section describes their call syntax. The ACLM calls do not use special data 
types or produce unique error messages. Refer to- the Introduction at the beginning of this 
manual for a description of the call syntax format. 
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ACLM-1 ACLM 



ACLM_$DOWN 

ACLM_$DOWN 

Deasserts a program's subsystem manager rights. 

FORMAT 

ACLM_$DOWN 

USAGE 

This call deasserts a program's rights to gain access to an object in a protected subsystem, 
which were asserted by a previous call to ACLM_$UP. 



v. 



ACLM ACLM-2 



ACLM SUP 



O 



o 
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ACLM_$UP 

Asserts a program's subsystem manager rights. 

FORMAT 

ACLM_$UP 

USAGE 

This call asserts a program's rights to gain access to an object in a protected subsystem, 
until a corresponding call to ACLM_$DOWN is made. 

Access Control List manager (ACLM) calls are used by subsystem manager programs in 
DOMAIN protected subsystems. A protected subsystem is a feature of the operating system 
that ensures that access to certain objects is restricted to certain programs which are called 
the managers of the subsystem that contains those objects. 

In fact, even a subsystem manager, which has the right to gain access to the protected 
objects, must call ACLM_$UP to assert its rights before it can actually use a protected 
object. Calling ACLM_$DOWN deasserts a program's rights as a subsystem manager. 

We recommend that you activate your rights as a subsystem manager for the minimum 
amount of time you will need them using ACLM_$UP and ACLM _$D OWN to bracket 
high-level statements or functions for which you need these rights. This ensures against 
inadvertent use of the protected objects. 

Calling ACLM_$UP increments a counter in your process; calling ACLM_$DOWN 
decrements it. Subsystem manager operations are enabled whenever the counter is nonzero. 
Having a counter instead of a flag ensures that if one routine enables subsystem manager 
rights, and calls a routine that enables and disables subsystem manager rights, the calling 
routine does not inadvertently lose its rights. 

Calling ACLM_$UP obtains all the subsystem rights to which you are entitled. If a 
program that is not a subsystem manager calls ACLM_$UP, it produces no effect, but does 
not return an error. Likewise, calling ACLM_$DOWN when subsystem manager rights 
were already deasserted has no effect. 

Protected subsystems and the reasons for using them are discussed completely in the 
Administering Your DOMAIN System. 
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CAL 



The CAL (Calendar) programming calls provide the calendar maintenance services. This section 
describes their data types, call syntax, and error codes. Refer to the Introduction at the 
beginning of this manual for a description of data type diagrams and call syntax format. 
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CAL DATA TYPES 



CONSTANTS 



CAL $STRING SIZE 



80 



Size of an ASCII string. 



DATA TYPES 



CAL $DPVAL T 



CAL $STRING T 



A double-precision floating point value. A 2-element 
array of 4-byte integers. (REAL*8 for FORTRAN 
programs.) 

An array of up to CAL _$STRING_ SIZE (80) 
characters. An ASCII string. 



CAL 
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CAL DATA TYPES 



CAL $TIMEDATE REC T 



6 integer, readable time format. The diagram 
below illustrates the cal_$timedate_rec_t data 
type: 



predefined 
type 



byte: 
offset 



field name 



o 



0: 


integer 


year 


2: 


integer 


month 


4: 


integer 


day 


6: 


integer 


hour 


8: 


integer 


minute 


10: 


integer 


second 



Field Description: 

year 

Integer representing the year. 

month 

Integer representing the month. 

day 

Integer representing the day. 

hour 

Integer representing the hour (24 hr.). 

minute 

Integer representing the minute. 

second 

Integer representing the second. 
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CAL DATA TYPES 



CAL $TIMEZONE REC T 



Specifies time difference and timezone name. The 
diagram below illustrates the 
cal_$timezone_rec_t data type: 



predefined t 
type o 


Dyte: 
ffset 

0: 

2: 

6: 

10: 








field name 




integer 




utc_delta 




char 


char 


char 


char 


tz_name 




integer 


drift 


time_$clock_t 


integer 







Field Description: 

utc_ delta 

Number of minutes difference from UTC. 

tz_name 

Time zone name. 



CAL_$TZ_NAME_T 
CAL $WEEKDAY T 



drift 

Drift adjustment. 

An array of up to 4 characters. Time zone name. 

A 2- byte integer. Specifies the day of the week. 
One of the following predefined values: 



CAL_$SUN 
Sunday 

CAL_$MON 
Monday 

CAL_$TUE 
Tuesday 

CAL_$WED 
Wednesday 

CAL_$THU 
Thursday 

CAL_$FRI 
Friday 



CAL_$SAT 
Saturday 



n 



CAL 
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CAL DATA TYPES 



STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



o 



o 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 

23). 



code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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CAL_$ADD_CLOCK 

CAL_$ADD_ CLOCK 

Computes the sum of two times. 

FORMAT 

CAL_$ADD_CLOCK (clockl, clock2) 

INPUT/OUTPUT PARAMETERS 

clockl 

Upon input The Coordinated Universal Time clock value to be added to clock2, in 

TIME_$CLOCK_T format. This data type is 6 bytes long. See the 
CAL Data Types section for more information. 

Upon output The sum of clockl and clock2, in TME_$CLOCK_T format. This 

data type is 6 bytes long. See the CAL Data Types section for more 
information. 

INPUT PARAMETERS 

clock2 

The Coordinated Universal Time clock value to be added to clockl, in 
TIME_$CLOCK_T format. This data type is 6 bytes long. See the CAL Data Types for 
more information. 



^_y 
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CAL_$APPLY_LOCAL_OFFSET 

CAL _ $APPLY_LOCAL _ OFFSET 

Computes the local time from a UTC time. 

FORMAT 

CAL_$APPLY_LOCAL_OFFSET (clock) 

INPUT/OUTPUT PARAMETERS 

clock 

Upon input Coordinated Universal Time clock value to which a local time zone offset 

will be added, in TIME_$CLOCK_T format. This data type is 6 bytes 
long. See the CAL Data Types section for more information. 

Upon output Adjusted clock value, representing the local time equivalent of the input 

parameter, in TIME_$CLOCK_T format. This data type is 6 bytes 
long. See the CAL Data Types section for more information. 



o 



USAGE 



CAL _$APPLY_LOCAL_ OFFSET adds the local time zone offset to the supplied clock 
value. 

To set the local time zone offset, you may either execute the Shell command TZ 
(TIME_ZONE) as described in the DOMAIN System Command Reference Manual, or 
you may use the CAL_$WRITE_TIMEZONE procedure. 
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CAL_$CLOCK_TO_SEC 

CAL_$OLOCK_TO_SEC 

Converts system clock units to seconds. 

FORMAT 

seconds = CAL_$CLOCK_TO_SEC (clock) 

RETURN VALUE 

seconds 

The computed equivalent of clock, in whole seconds. This is a 4-byte integer. 

If the number of seconds calculated from the input value does not represent a whole 
number, the fractional portion is truncated. 

INPUT PARAMETERS 

clock 

The value to be converted, in TME_$CLOCK_T format. This data type is 6 bytes long. 
See the CAL Data Types section for more information. 

USAGE 

CAL_$CLOCK_TO_SEC converts a value in system clock representation (UTC) to an 
equivalent value in whole seconds. 

The system clock value represents a time in units of 4 microseconds. 
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CAL $CMP CLOCK 



O 



o 



o 



CAL_$CMP_CLOCK 

Compares the values of two times. 

FORMAT 

integer = CAL_$CMP_CLOCK (clockl, clock2) 

RETURN VALUE 

integer 

The result of the logical compare of clockl to clock2. This is a 2-byte integer. 



Integer 
returned 

1 if clockl > clock2 

if clockl = clock2 

-1 if clockl < clock2 



INPUT PARAMETERS 

clockl 

The Coordinated Universal Time clock value to be compared to clock2, in 
TIME_$CLOCK_T format. This data type is 6 bytes long. See the CAL Data Types 
section for more information. 

clock2 

The Coordinated Universal Time clock value to be compared to clockl, in 
TIME_$CLOCK_T format. This data type is 6 bytes long. See the CAL Data Types for 
more information. 



CAL-9 CAL 



CAL_$DECODE_ASCII_DATE 

CAL_$DECODE_ASCII_DATE 

Decodes an ASCII string containing a date specification. 

FORMAT 

CAL_$DECODE_ASCII_DATE (string, stringlength, year, month, day, status) 

INPUT PARAMETERS 

string 

An ASCII character string, of length "stringlength" and in the form " year/month/day". 
This is an array of up to 80 characters. 

stringlength 

The number of characters in the string. This is a 2-byte integer. 

OUTPUT PARAMETERS 

year 

The year decoded from the string. This is a 2-byte integer. 

month 

The month decoded from the string. This is a 2-byte integer. 

day 

The day decoded from the string. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the CAL 
Data Types section for more information. 

Possible values are: 

CAL _ $BAD _ SYNTAX 

The string provided is not in "year/month/day" format. 

CAL _ $EMPTY_ STRING 

The string length is zero or the string contains only spaces. 

CAL_$OUT_OF_RANGE 

The value for month or day is invalid. 

USAGE 

CAL_$DECODE_ASCII_DATE translates the ASCII date in the supplied string into 
three integers representing the year, month, and day. The string must contain a year, a 
month, and a day, separated by slashes. 

If a year between 80 and 99 is specified, CAL_$DECODE_ASCII_DATE adds 1900 to it 
before returning. If a year between and 79 is specified, 2000 is added. 

Leading and trailing spaces are ignored. 
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CAL_ $DECODE_ ASCII_TIME 

CAL_$DECODE_ASCII_TIME 

Translates an ASCII string containing a time into integers. 

FORMAT 

CAL_$DECODE_ASCII_TIME (string, stringlength, hour, minute, second, status) 

INPUT PARAMETERS 

string 

An ASCII character string of length "stringlength" in the form "hour: minute" or 
"hour:minute:second", in 24-hour format. This is an array of up to 80 characters. 

stringlength 

The number of characters in the string. This is a 2 -byte integer. 

OUTPUT PARAMETERS 

hour 

The hour decoded from the string. This is a 2-byte integer. 

minute 

The minute decoded from the string. This is a 2-byte integer. 

O second 

The second decoded from the string. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the CAL 
Data Types section for more information. Possible values are: 

CAL _ $BAD _ SYNTAX 

The string is not in either "hour: minute :second" or "hour: minute" 
format. 

V_y CAL _$EMPTY_ STRING 

String length is zero or the string contains only spaces. 

CAL _ $OUT _ OF _RANGE 

The supplied ASCII value for hour, minute, or second is invalid. 

USAGE 

CAL _$DECODE_ASCII_ TIME translates the ASCII string into three integers, 
representing hours, minutes, and seconds. 

If the string specifies only hours and minutes, the value returned for seconds is zero. 
Leading and trailing spaces are ignored. 

) 
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CAL_$DECODE_ASCII_TZDIF 

CAL_$DECODE_ASCII_TZDIF 

Translates an ASCII string specifying a time zone into an offset from UTC. 

FORMAT 

CAL_$DECODE_ASCII_TZDIF (string, stringlength, tz-dif, tz-name, status) 

INPUT PARAMETERS 

string 

An ASCII string containing a time zone name or time zone difference. This is an array of 
up to 80 characters. 

A time zone name is one of the following strings: (EST) Eastern Standard Time ,(EDT) 
Eastern Daylight Time, (CST) Central Standard Time, (CDT) Central Daylight Time, 
(MST) Mountain Standard Time, (MDT) Mountain Daylight Time, (PST) Pacific Standard 
Time, (PDT) Pacific Daylight Time, (GMT) Greenwich Mean Time, and (UTC) 
Coordinated Universal Time. These are the eight standard U.S. time zone names, plus 
those for Greenwich Mean Time and Coordinated Universal Time. 

A time zone difference is a value which, when added to Coordinated Universal Time, 
produces the local time. Specify a time zone difference in the following form: 

[ + I - ] hour .minute 

The hour must be a number between and 12; the minute must be or 30. The sign is / 

optional. For example, Eastern Daylight Time may be represented as -4:00. 

stringlength 

The number of characters in the string. This is a 2-byte integer. 

OUTPUT PARAMETERS 

tz-dif 

The difference, in minutes, between the time zone specified in string and UTC. This is a ( 

2-byte integer. 

The value of tz-dif is negative for time zones west of the Greenwich Meridian and positive 
for time zones east of the Greenwich Meridian. 

tz-name 

The time zone name, in CAL_$TZ_NAME_T format. This is an array of up to 4 
characters. 

If the ASCII string contains a time zone name, this procedure returns that name in tz-name. 
If the ASCII string contains a time zone difference, this procedure returns spaces in tz-name. 



v 
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CAL_$DECODE_ASCII_TZDIF 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the CAL 
Data Types section for more information. Possible values are: 

CAL _ $EMPTY_ STRING 

String length is zero or the string contains only spaces. 

CAL _ $UNKNOWN_ TIMEZONE 

The string contains a time zone name that is unknown to this procedure. 

CAL_$BAD_SYNTAX 

The string appears to contain a time zone difference but is syntactically 
incorrect. 

CAL _ $INVALID _ TZDIF 

The string contains a time zone difference, but the number of hours is 
greater than 12 or the number of minutes is not or 30. 

USAGE 

CAL _$DECODE_ASCH_ TZDIF translates the supplied ASCII string into an offset from 
UTC, in units of minutes. The ASCII string can contain a time zone name or a time zone 
difference. 
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CAL_$DECODE_LOCAL_TIME 

CAL _ $DECODE _LOCAL _ TIME 

Returns the local time in integer format. 

FORMAT 

CAL_$DECODE_LOCAL_TIME (decoded_clock) 

OUTPUT PARAMETERS 

decoded _ clock 

The local time, in CAL _$ TIMED ATE _REC_T format. This data type is 12 bytes long. 
See the CAL Data Types section for more information. 

USAGE 

CAL _$DECODE_ LOCAL _ TIME returns the local time in "year, month, day, hour, 
minute, second" format. 
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CAL_$DECODE_TIME 

CAL _ $DECODE _ TIME 

Translates an internal system clock value into a readable date and time. 

FORMAT 

CAL_$DECODE_TIME (clock. decoded_clock) 

INPUT PARAMETERS 

clock 

The value to be translated, in TIME_$CLOCK_T format. This data type is 6 bytes long. 
See the CAL Data Types section for more information. 

OUTPUT PARAMETERS 

decoded _ clock 

A date and time, in CAL_$TIMEDATE_REC_T format. This data type is 12 bytes 
long. See the CAL Data Types section for more information. 

USAGE 

CAL _$DECODE_ TIME translates a time in TIME_$CLOCK_T form into 
CAL_$TIMEDATE_REC_T ("year, month, day, hour, minute, second") form. 

This routine translates clock values, such as those returned from the TIME_$CLOCK, 
CAL_$GET_LOCAL_TIME, CAL _$APPLY_ LOCAL _ OFFSET, and 
CAL $ENCODE TIME routines. 
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CAL_ $ENCODE_TIME 

CAL_$ENCODE_TIME 

Translates a date and time from integer format into a system clock representation. 

FORMAT 

CAL_$ENCODE_TIME (decoded_clock, clock) 

INPUT PARAMETERS 

decoded _ clock 

A date and time, in CAL_$TIMEDATE_REC_T format. This data type is 12 bytes 
long. See the CAL Data Types section for more information. 

OUTPUT PARAMETERS 



clock 



The system clock equivalent value of decoded _ clock, in TIME_$CLOCK_T format. This \^ y 

data type is 6 bytes long. See the CAL Data Types section for more information. 



USAGE 



CAL _$ENCODE_ TIME translates the date and time specified by decoded _ clock into the 
equivalent system representation. 
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CAL_$FLOAT_CLOCK 

CAL _ $FLOAT _ CLOCK 

Converts a system clock representation to the equivalent number of seconds, in 
double-precision floating-point format. 

FORMAT 

CAL_$FLOAT_CLOCK (clock, f loat_seconds) 

INPUT PARAMETERS 

clock 

The value to be converted, in TME_$CLOCK_T format. This data type is 6 bytes long. 
See the CAL Data Types section for more information. 

OUTPUT PARAMETERS 

) float _ seconds 

The converted value of clock, in seconds. This is in double-precision floating-point 
(REAL*8) format. 

USAGE 

CAL _$FLOAT_ CLOCK converts a clock value in UTC format to the equivalent number 
of seconds expressed as a double-precision floating-point number. 

Unlike CAL_$CLOCK_TO_SEC, CAL _$FLOAT_ CLOCK does not truncate the 
fractional portion of the conversion. 
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CAL_$GET_INFO 

CAL_$GET_INFO 

Returns local time zone information. 

FORMAT 

CAL_$GET_INFO (timezone_info) 

OUTPUT PARAMETERS 

t imezone _ info 

A record containing the name of the local time zone and its offset from UTC, in 
CAL_$TIMEZONE_REC_T format. This data type is 12 bytes long. See the CAL Data 
Types section for more information. 

USAGE 

CAL _$GET_ INFO returns the name of the local time zone and the difference between 
local time and Coordinated Universal Time (UTC). 
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CAL_$GET_LOCAL_TIME 

CAL_$GET_LOCAL_TIME 

Returns the current local time in system clock representation. 

FORMAT 

CAL_$GET_LOCAL_TIME (clock) 

OUTPUT PARAMETERS 

clock 

The current local time, in TIME_$CLOCK_T format. This data type is 6 bytes long. See 
the CAL Data Types section for more information. 

This is the number of 4-microsecond periods that have elapsed since January 1, 1980, 00:00. 
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CAL_$REMOVE_LOCAL_OFFSET 

CAL_$REMOVE_LOCAL_OFFSET 

Computes the UTO time from local time. 

FORMAT 

CAL_$APPLY_LOCAL_OFFSET (clock) 

INPUT/OUTPUT PARAMETERS 

clock 

Upon input Local time from which the local time offset will be removed, in 

TIME_$CLOCK_T format. This data type is 6 bytes long. See the 
CAL Data Types section for more information. 

Upon output Adjusted clock value, representing the UTC equivalent of the input 

parameter, in TME_$CLOCK_T format. This data type is 6 bytes 
long. See the CAL Data Types section for more information. 

USAGE 

CAL _$REMOVE_ LOCAL _ OFFSET subtracts the local time zone offset from the 
supplied clock value. 

To set the local time zone offset, you may either execute the Shell command TZ 
(TIME_ZONE) as described in the DOMAIN System Command Reference, or you may 
use the CAL _$ WRITE _TMEZONE procedure. 
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CAL_$SEC_TO_CLOCK 

CAL _ $SEC _ TO _ CLOCK 

Converts seconds to system clock units. 

FORMAT 

CAL_$SEC_TO_CLOCK (seconds, clock) 

INPUT PARAMETERS 

seconds 

The value to be converted. This is a 4-byte integer. 

OUTPUT PARAMETERS 

clock 

The computed equivalent of seconds, in TIME_$CLOCK_T format. This data type is 6 
bytes long. See the CAL Data Types section for more information. 

USAGE 

CAL _$SEC_ TO _ CLOCK converts a value representing seconds to an equivalent value in 
4-microsecond units. 

No overflow detection is performed. 
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CAL _ $SUB _ CLOCK ^-^ 

Subtracts the values of two times. 'v._^' 

FORMAT 

value = CAL_$SUB_CLOCK (clockl, clock2) 

RETURN VALUE 

value 

The Boolean result of the subtraction of clock2 from clockl. The returned value is TRUE if 
the result is >= 0. 

INPUT/OUTPUT PARAMETERS 

clockl /"^ 

Upon input The Coordinated Universal Time clock value from which clock2 is 

subtracted, in TIME_$CLOCK_T format. This data type is 6 bytes 
long. See the CAL Data Types section for more information. 

Upon output The difference between clockl and clock2, in TIME_$CLOCK_T 

format. This data type is 6 bytes long. See the CAL Data Types section 
for more information. 

INPUT PARAMETERS "^ 

clock2 

The Coordinated Universal Time clock value to be subtracted from clockl, in 
TIME_$CLOCK_T format. This data type is 6 bytes long. See the CAL Data Types 
section for more information. 
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CAL_$WEEICDAY 

Computes the day of the week given a year, month, and day. 

FORMAT 

weekday = CAL_$WEEKDAY (year, month, day) 

RETURN VALUE 

weekday 

The computed day of the week, in CAL_$WEEKDAY_T format. This is a 2-byte 
integer. Returns one of the following predefined values: 

CAL_$SUN, CAL_$MON. CAL_$TUE. CAL_$WED, 
CAL_$THU. CAL_$FRI, CAL_$SAT . 

Their ordinal values are through 6. 

INPUT PARAMETERS 

year 

The year for which the weekday is desired. This is a 2-byte integer. 

month 

The month for which the weekday is desired. This is a 2-byte integer. 

day 

The day of the month for which the weekday is desired. This is a 2-byte integer. 

USAGE 

CAL_$WEEKDAY computes the day of the week for any Gregorian date. 
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CAL_$WRITE_TIMEZONE 

CAL _ $WRITE _ TIMEZONE , -^ 

Writes local time zone information onto the boot volume. V_y 

FORMAT 

CAL_$WRITE_TIMEZONE (timezone_inf o. status) 

INPUT PARAMETERS 

timezone _ info 

The time zone information to be recorded, in CAL_$TIMEZONE_REC_T format. This 
data type is 12 bytes long. See the CAL Data Types section for more information. 

The supplied time zone information includes the name of the time zone and its offset form 
UTC. 

OUTPUT PARAMETERS V .^ 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the CAL 
Data Types section for more information. 

USAGE 

CAL _$WRITE_ TIMEZONE writes the supplied time zone information onto the logical 
disk volume from which the operating system was started. 

This procedure is invalid on a diskless node, and returns a nonzero status. 

The time zone information written by this procedure is used by subsequent calls to 
CAL_$DECODE_LOCAL_TIME, CAL _$GET_ LOCAL _ TIME, 
CAL_$APPLY_LOCAL_OFFSET, and CAL _$GET_ INFO. 

A nonzero status indicates a system problem in reading or writing the volume. 
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ERRORS 

STATUS _$OK 

Successful completion. 

CAL _ $B AD _ SYNTAX 

Invalid syntax for date or time specification. 

CAL _ $EMPTY_ STRING 

An empty string was passed to a decode routine. 

CAL _ $INVALID _ TZDIF 

Invalid time-zone difference. 

CAL_$OUT_OF_RANGE 

Date or time specification invalid. 

CAL_$UNKNOWN_TMEZONE 

Timezone specified is unknown. 
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CTM 



The CTM (Color Table Manager) programming calls allow different GPR applications running on 
the same node to share the color map without interfering with each other. This section describes 
their data types, call syntax, and error codes. Refer to the Introduction at the beginning of this 
manual for a description of data type diagrams and call syntax format. 
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CTM DATA TYPES 



DATA TYPES 



GPR $PLXEL VALUE T 



CMT $PKEL VALUE VECTOR T 



CTM $ALLOC OPTIONS T 






A 4-byte integer. Defines an index into the color 
map to identify the color of an individual pixel. 

An array of GPR_$PLXEL_VALUE_T that stores 
multiple pixel values. 

A 2-byte integer. Identifies the type of pixel values 
that can be affected by a CTM call. Specify only 
one of the following predefined values: 



NONE 

If you specify for FORTRAN/C or [ ] for 

Pascal, then any available pixel value is 

returned. 



CTM_$CONTIGUOUS 

The allocated pixel values must be contiguous. 
In this case, only the smallest pixel value in 
the range is returned. 



V,_... 



CTM_$ZERO_ONLY 

Only pixel values with zero in a given plane 
will be allocated. If the plane is greater than 
or equal to zero, then this parameter specifies 
which plane must have zero bits. If the plane 
is less than 0, then the CTM package will 
choose a plane and return it 



CTM_$ONE_ONLY 

This is similar to CTM_$ZERO_ONLY except 

that the plane in question must contain only 

ones. 

CTM_$BOTH 

Pairs of pixel values will be allocated where 
the two members of each pair differ only in 
the given plane. If the plane is less than zero, 
the CTM package selects a plane for you. 



CTM 
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STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



o 



o 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 ■ 

23). 



o 



code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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CTM_$ALLOC_PV 

CTM_$ALLOC_PV 

Allocates available pixel values and sets their use counts to one. 

FORMAT 

CTM_$ALLOC_PV (count, opt, plane, pixel_values, status) 

INPUT PARAMETERS 

count 

Specifies the number of pixel values (or pixel value pairs). This parameter is a 2-byte 
integer. 

opt 

Specifies the constraints placed on pixel values to be allocated, in 

CTM_$ALLOC_ OPTIONS _T format. This parameter is a 2-byte integer. Specify only 

one of the following values: 

NONE If you specify for FORTRAN /C or [ ] for Pascal, then any available 

pixel values are returned. 

CTM_ $CONTIGUOUS 

The allocated pixel values must be contiguous. In this case, only the 
smallest pixel value in the range is returned. 

CTM_$ZERO_ONLY 

Only pixel values with zero in a given plane will be allocated. If the 
plane is greater than or equal to zero, then this parameter specifies which 
plane must have zero bits. If the plane is less than 0, then the CTM 
package will choose a plane and return it. 

CTM_$ONE_ONLY 

This is similar to CTM _$ZERO_ ONLY except that the plane in 
question must contain only ones. 

CTM_$BOTH Pairs of pixel values will be allocated where the two members of each pair 
differ only in the given plane. If the plane is less than zero, the CTM 
package selects a plane for you. If this option is selected, the count 
parameter specifies the number of pairs, and the returned pixel _ values 
parameter will contain only the smallest (i.e., zero bit) number of each 
pair. 

INPUT/OUTPUT PARAMETERS 

plane 

Specifies the bit plane required by the opt parameter. This parameter is a 2-byte integer. 

OUTPUT PARAMETERS 

pixel _ values 

The allocated pixel values, in CTM _$PB£EL_ VALUE _ VECTOR _T format. This 
parameter is an array of 4-byte integers. 
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status 

The completion status, in STATUS _$T format. This parameter is 4 bytes long. See the 
CTM Data Types section for more information. 

USAGE 

The CTM_$ALLOC_PV routine searches for pixel values that have use counts of zero and 
also satisfy the constraints specified by the opt parameter. The allocated values are 
returned in the pixel _ values parameter, and their use counts are set to one. 

The CTM (Color Table Manager) package operates on a data base of pixel values that is 
shared by all processes using GPR in direct mode or frame mode. The CTM calls allow 
different applications running on the same node to share the color map without interferring 
with one another. 

Note that borrow mode applications have a separate, private copy of the color map, which 
is initialized to default values by GPR_$INIT. 

The concept of a shared color map corresponds to the fact that there is a single physical 
color map for the display device. For example, if process A calls 

GPR_$SET_COLOR_MAP, and process B calls GPR_$INQ_COLOR_MAP for the 
same pixel values, process B will see the changes made by process A. 

The CTM package keeps track of how many processes can access a pixel value by 
maintaining a use count for each pixel value. All pixel values except those preallocated by 
the Display Manager (see below) have an initial use count of zero which means that they are 
available for allocation. 

As each process gains access to a pixel value, the pixel value's use count is incremented. 
For example, if five processes are sharing a pixel value, its use count is five. When a 
process releases a pixel value (using CTM_$RELEASE_PV), its use count is decremented. 
When the use count reaches zero, the pixel value can be reallocated. 

The CTM routines are "advisory" in nature, and do not affect the validity of calls to 
GPR _$SET_ COLOR _MAP. Any pixel value may be set by any program, including the 
( ) pixel values used by the Display Manager for window colors. The Display Manager 

~-^ preallocates values 0, 1, and 7 through 15. However, the Display Manager will release pixel 

values 8 through 15 when you use the MONO command (see DOMAIN System Command 
Reference). 

The total number of available pixel values depends on the display type and the number of 
planes on the node as follows: 

Display Type Available Pixel Values 



O 



/" 



o 



Monochrome 2 

4-plane color 16 

8-plane color 256 

Even monochrome displays have "color maps". Monochrome color maps control whether 
the display is operating in white-on-black or black-on-white. For example, applications can 
invert the display by calling GPR _$SET_ COLOR _MAP for pixel values zero and one, 
specifying the colors white and black, as desired. This feature is available in direct, frame, 
and borrow mode. 
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Using the CTM Routines 

Include the insert file /sys/ins/ctm.ins.pas, /sys/ins/ctm.ins.c, or /sys/ins/ctm.ins.ftn in 
programs that use the CTM package. 

The easiest way to use the CTM package is for all processes to use 
CTM_$FIND_ COLOR. In this way, the CTM package takes care of all the 
"bookkeeping" and you can access any color that you need. For example, if process A 
wants to use light blue, it supplies the pixel value (200,200,255) to 

CTM_$FIND_ COLOR. If the color is in the color map, the CTM package increments its 
use count, making it available to process A. If light blue is not in the color map, CTM 
creates a light blue entry in the color map and increments its use count. If process B wants 
to use the same color, it also makes a call to CTM_$FIND_ COLOR. 

If you want to allocate colors yourself, use CTM_$ALLOC_PV. You may want to do this 
if you plan to change the color values and don't want to affect other processes (and don't 
want other processes to hinder your use of the color map). When you use 
CTM_$ALLOC_PV, there are two ways that other processes can use the values: 

1. Use CTM_$MARK_READ_ONLY to make the pixel values available to 
other processes. This call marks the pixel values as read-only and other 
processes that use CTM_$FIND_ COLOR can use them (but they cannot 
change them). 

2. This method involves sharing data between processes or between independent 
components of the same process (for example, passing parameters between 
processes or using the C functions fork or pipe). If you obtain pixel values from 
another process and that process might terminate first (or might release the 
pixel values first), you can use CTM_$INC_USE_COUNT to indicate your 
intent to continue using those pixel values. 

When you are through using a set of pixel values, you can release them using 
CTM_$RELEASE_PV. This routine decrements the use count of selected pixel values. 
When a pixel value's use count reaches zero, it is available for reallocation. The CTM 
package automatically decrements the use count of any pixel values that have been 
allocated by a program when the program terminates. 

Using the CTM_$ALLOC_PV Options 

If your application needs to change colors frequently, the easiest method is to use 
CTM_$ALLOC_PV with no options. Use the options when you need to perform more 
sophisticated tasks such as redrawing a portion of an image in a different color. An 
example of this is performing an XOR raster operation when rubberbanding a line or 
dynamically dragging an object across the screen (see GPR _$SET_ RASTER _ OP for 
more information on raster operations). 

When dragging an object across the screen, an application needs to repeatedly redraw and 
erase the object without disturbing the existing geometry. In an XOR operation, when a 
dragged object crosses an existing piece of geometry, each intersection point is redrawn in a 
different color. After the object passes by, the intersection point is redrawn in its original 
color. 

XOR operations work well on monochrome nodes but on a color node it is faster to 
explicitly set the draw value to one or zero. 
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For example, assume that your application is drawing in red, green, and blue, and wants to 
draw intersection points in black. Use the following procedure: 

1. Use CTM_$ALLOC_PV with the CTM_$BOTH option to allocate three 
pairs of pixel values. The values in each pair differ only in one plane. 

2. Use GPR_$SET_ COLOR _ MAP to assign red, green, and blue to the first 
elements in each pair and assign black to the second element in each pair. For 
example, the following illustration shows three pixel value pairs that differ only 
in one plane: 

Pixel Value Pairs Binary Representation Assigned Color 

1 1 red 

3 Oil black 

blue 

2 10 black 

5 1 1 green 

7 111 black 



3. Use GPR_$SET_ PLANE _ MASK to limit operations to the two planes. 

4. Use the default raster operation (GPR _$SET_ RASTER _ OP operation 3). 

Drawing ones in the allocated plane changes the image from its original color to black. 
Switching back to zeros reverts the image to its original color. 
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CTM_$FIND_COLOR ^ 

Searches for a pixel value (within a specified distance) that already contains a desired color. V 

If one does not exist, a new pixel value is allocated and set to the desired color. 

FORMAT 

CTM_$FIND_COLOR (color. max_distance, pixel_value, status) 

INPUT PARAMETERS 

color 

The desired color, in GPR_$COLOR_T format. This parameter is a 4-byte integer that 
specifies values for red, green, and blue. 

max _ distance 

A distance in the color space (see Usage). This parameter is a 2-byte integer. 

\ 
OUTPUT PARAMETERS 

pixel _ value 

The resulting color value, in GPR_$PLXEL_ VALUE _T format. This parameter is a 
4-byte integer. 

status 

The completion status, in STATUS _$T format. This parameter is 4 bytes long. See the ^ 

CTM Data Types section for more information. 



USAGE 



This routine treats the RGB color space as though it were ordinary 3D geometry. That is, 
the distance between two color values is the square root of the sum of the squares of the 
absolute differences in RGB intensity. 

CTM _$FIND_ COLOR searches for a pixel value that already contains the desired color 
within the specified distance. First it searches the pixels marked read-only (see 
CTM _$MARK_ READ _ ONLY). If the value is found, the routine increments the pixel's 
use count. Otherwise, a new pixel value is allocated, set to the specified color, and marked 
read-only. The routine uses GPR_$INQ_ COLOR _MAP to determine current color 
settings and GPR_$SET_COLOR_MAP to establish new colors. 

This procedure finds the best match, not the first match. Therefore, if you want the closest 
existing pixel value, use lastof(integer) for the max_ distance parameter. 



^ y 



CTM CTM- 8 



) 



CTM_ $INC _USE_ COUNT 

CTM_$INC_USE_COUNT 

Increments the use count of previously allocated pixel values. 

FORMAT 

CTM_$INC_USE_COUNT (count, opt, plane, pixel_values. status) 

INPUT PARAMETERS 

count 

Specifies the number of pixel values (or pixel value pairs). This parameter is a 2-byte 
integer. 

opt 

Specifies the constraints placed on pixel values to be allocated, in 

CTM_$ALLOC_ OPTIONS _T format. This parameter is a 2-byte integer. Possible 

values are the following: 

CTM_ $CONTIGUOUS 
CTM_ $ZERO _ ONLY 
CTM_$ONE_ONLY 
CTM_$BOTH 

plane 

Specifies the bit plane required by the opt parameter. This parameter is a 2-byte integer. 

pixel _ values 

The allocated pixel values, in CTM_$PIXEL_VALUE__VECTOR_T format. This 
parameter is an array of 4-byte integers. 

OUTPUT PARAMETERS 

status 

The completion status, in STATUS _$T format. This parameter is 4 bytes long. 

USAGE 

If you obtain pixel values from another process, and that process might terminate first (or 
might release the pixel values first), you can use this routine to indicate your intent to 
continue using those pixel values. 

Only use this call if you are sharing data between processes or between independent 
components of the same process (for example, passing parameters between processes or using 
the C functions fork or pipe). If you are accessing pixel values using 
CTM_$FIND_ COLOR, you don't need to use this call since CTM_$FIND_ COLOR 
automatically increments the use count for you. 

The use count is a 16-bit word that can take on any non-negative value. If the value is 
zero, it signifies that the pixel value is available to be allocated (see Usage under 
CTM_$ALLOC_PV for more information). 

The count, opt, and plane arguments are used only to determine the actual pixel values 
specified in the pixel _ values parameter. 
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CTM $MARK READ ONLY 



Marks pixels as shareable by other processes. Shareable pixel values may be allocated using 
CTM $FIND COLOR. 



FORMAT 

CTM_$MARK_READ_ONLY (count, opt, plane, pixel_values, status) 

INPUT PARAMETERS 

count 

Specifies the number of pixel values (or pixel value pairs). This parameter is a 2-byte 
integer. 

opt 

Specifies the constraints placed on pixel values to be allocated, in 

CTM_$ALLOC_ OPTIONS _T format. This parameter is a 2-byte integer. Possible 

values are the following: 

CTM_ $CONTIGUOUS 
CTM_ $ZERO _ ONLY 
CTM_$ONE_ONLY 
CTM_$BOTH 

See CTM_$ALLOC_PV for more information. 

plane 

Specifies the bit plane required by the opt parameter. This parameter is a 2-byte integer. 

pixel _ values 

The allocated pixel values, in CTM _$PLXEL_ VALUE _ VECTOR _T format. This 
parameter is an an array of 4-byte integers. 

OUTPUT PARAMETERS 

status 

The completion status, in STATUS _$T format. This parameter is 4 bytes long. See the 
CTM Data Types section for more information. 

USAGE 

If you obtain pixel values using CTM_$ALLOC_PV, the CTM package assumes that you 
will change the colors assigned to these pixel values from time to time. If you do not plan 
to change the colors, you may make them available to other programs that call 
CTM_$FIND_ COLOR. To make them available, you call 
CTM_$MARK_READ_ONLY after calling GPR_$SET_ COLOR _MAP. 



V... 



CTM CTM- 10 



o 



CTM_$RELEASE_PV 

CTM_$RELEASE_PV 

Decrements the use count of selected pixel values. A pixel value is made available to other 
processes when its use count reaches zero. 

FORMAT 

CTM_$RELEASE_PV (count, opt. plane. pixel_values. status) 

INPUT PARAMETERS 

count 

Specifies the number of pixel values (or pixel value pairs). This parameter is a 2-byte 
integer. 

opt 

Specifies the constraints placed on pixel values to be released, in 

CTM_$ALLOC_OPTIONS_T format. This parameter is a 2-byte integer. Possible 
values are the following: 

CTM_ $CONTIGUOUS 
CTM_ $ZERO _ ONLY 
CTM_$ONE_ONLY 
CTM_$BOTH 

See CTM_$ALLOC_PV for more information. 

plane 

Specifies the bit plane required by the opt parameter. This parameter is a 2-byte integer. 

pixel _ values 

The released pixel values, in CTM_$PIXEL_ VALUE _ VECTOR _T format. This 
parameter is an array of 4-byte integers. 

OUTPUT PARAMETERS 

status 

The completion status, in STATUS _$T format. This parameter is 4 bytes long. See the 
CTM Data Types section for more information. 

USAGE 

When you are finished using a set of pixel values, you should return them using this 
routine. The routine decrements the use count. When the use count reaches zero, the pixel 
values will be available to other callers. If you don't make this call, any pixel values you 
have allocated will be automatically released when your program terminates execution. 

An error is returned if you attempt to decrement a use count below zero or if you attempt 
to decrement a use count that you (your process, at or above the current program level) 
have not previously incremented.. 
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ERRORS / 

'V, 
STATUS _$OK 

Successful completion. 

CTM_$NOT_ALLOCATED 

The pixel values specified by CTM_$RELEASE_PV, CTM _$INC_ USE _ COUNT, 
or CTM_$MARK_READ_ONLY were not allocated. Pixels values must be 
allocated by CTM_$ALLOC_PV or CTM _$FIND_ COLOR before they can be 
used by other CTM calls. 

CTM_$CAN'T 

The CTM package was unable to allocate the requested pixel values because there is 
no more space available in the color map. Either use GMR_$FIND_ COLOR to 
locate an appropriate color that is already allocated, or use CTM_$RELEASE_PV 
to deallocate values. 

CTM _ $NO _ SPACE f 

The CTM package was unable to allocate memory for its tables. 
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The EC2 (Level 2 Eventcount) programming calls create and manage eventcounts for 
synchronizing program events. This section describes their data types, call syntax, and error 
codes. Refer to the Introduction at the beginning of this manual for a description of data type 
diagrams and call syntax format. 
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CONSTANTS 



EC2 $ALWAYS READY EC 



V 



Replaces an EC2_$PTR pointer to indicate that 
the event is always ready. 



DATA TYPES 



EC2 $EVENTCOUNT T 



An eventcount. The diagram Jbelow illustrates the 
EC2_$EVENTCOUNT_T d"ata type: 



predefined 
type 


byte: 
offset 

0: 
4: 






field name 




integer 


value 




integer 




awaiters 



Field Description: 

value 

The value of the eventcount. 



EC2_$PTR_LIST_T 

EC2_$PTR_T 

EC2 $VAL LIST T 



awaiters 

Reserved for internal use by the EC2 manager. 

An array of up to 32 pointers to eventcounts. Each 
pointer is a 4-byte integer in EC2_$PTR_T 
format. 

A 4-byte integer. A pointer to an eventcount. 

An array of trigger values for each of the 
eventcounts in an eventcount pointer list. Each 
trigger value is a positive, 4-byte integer. 
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STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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EC2_ SAD VANCE 

EC2_$ADVANCE 

Advances the specified user-defined eventcount by one. 

FORMAT 

EC2_$ADVANCE (eventcount, status) 

INPUT/OUTPUT PARAMETERS 

eventcount 

Eventcount to be advanced, in EC2_$EVENTCOUNT_T format. This data type is 6 
bytes long. See the EC2 Data Types section for more information. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the EC2 
Data Types section for more information. 

USAGE 

EC2_$AD VANCE advances a user-defined eventcount; do not use this call to advance a 
system-defined eventcount. A user-defined eventcount is one that a process establishes with 
EC2_$INIT. 

In order to advance an eventcount, you must have read and write access to the emory 
location where the eventcount is located. Typically, the eventcount is in a mapped file, and 
you should use MS_$MAPL to map this file. 

When you map a file containing an eventcount, you should request a shared write lock. 
Only processes on the same node can concurrently get shared write locks on the same file. 
See MS_$MAPL for more information about mapping a file. 
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EC2_$INIT 

Initializes a user-defined eventcount. 

FORMAT 

EC2_$INIT (eventcount) 

INPUT PARAMETERS 
None. 

OUTPUT PARAMETERS 

eventcount 

Initialized eventcount, in EC2_$EVENTCOUNT_T format. This data type is 6 bytes 
long. See the EC2 Data Types section for more information. 

USAGE 

Use this call to initialize a user-defined eventcount. Initialize the eventcount within a file 
that several programs will share. First, map the file for shared write access (by requesting a 
shared write lock.) Then use EC2_$INIT to initialize the eventcount. All programs that 
use the eventcount must first map the file containing the eventcount. See the Mapped 
Segment (MS) calls for more information on mapping. 

Do not use EC2_$INIT to initialize a system-defined eventcount; the system automatically 
initializes eventcounts associated with system events. To use a system-defined eventcount, 
use the system call that gets the address of the eventcount you want to wait on. For 
example, use MBX_$GET_EC to get the address of a mailbox eventcount. 
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EC2_$READ 

EC2_$READ 

Returns the current value of an eventcount. 

FORMAT 

ec-value = EC2_$READ (eventcount) 

RETURN VALUE 

ec-value 

Value of the eventcount. This is a positive, 4-byte integer. 

INPUT PARAMETERS 

eventcount 

Eventcount, in EC2_$EVENTC0UNT_T format. This data type is 6 bytes long. See 
the EC2 Data Types section for more information. 

OUTPUT PARAMETERS 
None. 

USAGE 

Use EC2 $READ to read the value of an eventcount. 
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EC2_$WAIT 

EC2_$WAIT 
( ) Waits until any of a list of eventcounts reaches or exceeds a trigger value. 

FORMAT 

ec-satisfied = EC2_$WAIT (ec-plist, ec-vlist, ec-count. status) 

RETURN VALUE 

ec-satisfied 

An ordinal number indicating the eventcount that is satisfied. This is a positive, 2-byte 
integer. 

INPUT PARAMETERS 

Oec-plist 
Array of pointers to eventcounts. Each pointer is a 4-byte integer in EC2_$PTR_T 
format. The total number of eventcounts in ec-plist lists in any one node cannot exceed 32. 

ec-vlist 

Array of trigger values for each of the eventcounts in the ec-plist. Each trigger value is a 
positive, 4-byte integer. When any of the eventcounts from the ec-plist reaches its trigger 
value, the EC2_$WAIT call returns. 

ec- count 

Number of eventcounts in the ec-plist. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the EC2 
Data Types section for more information. 

USAGE 

EC2 _ $WAIT waits until one of the eventcounts in the ec-plist reaches its trigger value in 
the ec-vlist. When an eventcount reaches its trigger value, EC2_$WAIT returns an index 
value indicating the position (in the ec-plist) of the eventcount that is satisfied. The index 
starts from 1; that is, ec-satisfied equals 1 if the first eventcount in the ec-plist is satisfied. 

Several eventcounts may have been satisfied by the time this call wakes your program. The 
index number returned refers to only one of the eventcounts. If more than one eventcount 
is satisfied, EC2_$WAIT returns the one with the smallest subscript. 

EC2_$WAIT only returns when an eventcount advances, regardless of the asynchronous 
fault handling setting. An asynchronous fault, such as a "quit", is generated outside your 
program. If an asynchronous fault occurs during an EC2_$WAIT call, your program's 
response depends on the type of error handling that is in effect. 
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EC2 $WAIT 



If asynchronous faults are enabled, a program can respond to an asynchronous fault with a 
clean-up handler or fault handler. If an asynchronous fault occurs during an E02_$WAIT 
call, and asynchronous faults are enabled, the program will perform one of the following: 

• Execute the clean-up handler, if the program has one. 

© Execute the fault handler, if the program has one. If the fault handler returns 
control to the interrupted code, EC2_$WAIT continues waiting. 

o If the program has neither a clean-up handler nor a fault handler, the program 
aborts if an asynchronous fault occurs. 

If a program disables asynchronous faults and such a fault occurs during an EC2_$WAIT, 
then the program ignores the fault and continues waiting. 

Note that the call EC2_$WAIT_SVC responds differently to asynchronous faults. 
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EC2_$WAIT_SVC 

EC2_$WAIT_SVC 

Waits until any of a list of eventcounts reaches or exceeds a trigger value. 

FORMAT 

ec-satisfied = EC2_$WAIT_SVC (ec-plist, ec-vlist, ec-count, status) 

RETURN VALUE 

ec-satisfied 

An ordinal number indicating the eventcount that was satisfied. This is a positive, 2-byte 
integer. 

INPUT PARAMETERS 

ec-plist 

Array of pointers to eventcounts. Each pointer in the array is a 4-byte integer in 
EC2_$PTR_T format. The total number of eventcounts in ec-plist lists in any one node 
cannot exceed 32. 

ec-vlist 

Array of trigger values for each of the eventcounts in the ec-plist. Each trigger value is a 
positive, 4-byte integer. When any of the eventcounts from the ec-plist reaches its trigger 
value, the EC2_$WAIT_SV0 call returns. 

ec-count 

Number of eventcounts in the ec-plist. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the EC2 
Data Types section for more information. 

USAGE 

EC2_$WAIT_SVC waits until one of the eventcounts in the ec-plist reaches its trigger 
value in the ec-vlist. When an eventcount reaches its trigger value, EC2_$WAIT_SVC 
returns an index value indicating the position (in the ec-plist) of the eventcount that is 
satisfied. The index starts from 1; that is, ec-satisfied equals 1 if the first eventcount in the 
ec-plist is satisfied. 

Several eventcounts may have been satisfied by the time this call wakes your program. The 
index number returned refers to only one of the eventcounts. If more than one eventcount 
is satisfied, EC2_$WAIT_SVC returns the one with the smallest subscript. 

In certain cases, EC2_$WAIT_SVC returns the error EC2_$WAIT_QUIT if an 
asynchronous fault occurs during the EC2_$WAIT_SVC call. An asynchronous fault, 
such as a "quit", is generated outside your program. If an asynchronous fault occurs 
during an EC2_$WAIT_SVC call, your program's response depends on the type of error 
handling that is in effect. 
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If asynchronous faults are enabled, a program can respond to an asynchronous fault with a 
clean-up handler or a fault handler. If an asynchronous fault occurs during an 
EC2_$WAIT_SVC call, and asynchronous faults are enabled, the program will perform 
one of the following: 

• Execute the clean-up handler, if the program has one. 

• Execute the fault handler, if the program has one. If the fault handler returns 
control to the interrupted code, EC2_$WAIT_SVC returns the error 
EC2_$WAIT_QUIT. 

• If the program has neither a clean-up handler nor a fault handler, the program 
aborts if an asynchronous fault occurs. 

If a program disables asynchronous faults and such a fault occurs during an 
EC2_$WAIT_SVC, then the program does not handle the fault. However, 
EC2_$WAIT_SVC returns the error EC2_$WAIT_QUIT. 

Note that the call EC2_$WAIT responds differently to asynchronous faults. 
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ERRORS 

STATUS _$OK 

Successful completion. 

EC2 _ $BAD _EVENTCOUNT 
Bad eventcount. 

EC2 _ $INTERNAL _ERROR 
Internal error. 

EC2 _ $NO _ WAIT _ENTRIES 

Internal table exhausted. 

EC2_$WAIT_QUIT 

Process quit while waiting. 
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ERROR 



The ERROR programming calls provide status printing and interpretation. This section 
describes their data types and call syntax. The ERROR calls do not produce unique error 
messages. Refer to the Introduction at the beginning of this manual for a description of data 
type diagrams and call syntax format. 
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DATA TYPES 



ERROR $INTEGER32 



A 2-byte integer. Possible values are integers from 
-1 through 2147483647. 



ERROR_$STRING_PTR_T 

ERROR_$STRING_T 
STATUS $T 



A 4-byte integer. A pointer to an 
ERROR _$STRING_T data type. 

An array of up to 80 characters. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 


31 






field name 



0: 


integer 


all 


0: 


* 31 


or 

I 24 

I 





fail 






subsys 


1: 




16 


mode 


2: 


integer 


code 



r 



v_ 



Field Description: 

all 

All 32 bits in the status code. 



fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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ERROR _$CODE 

Returns the module-specific code from a status code. 

FORMAT 

code = ERROR_$CODE (status) 

RETURN VALUE 

code 

The module-specific code component of the supplied status code. This is a 2-byte integer. 

INPUT PARAMETERS 

status 

OA status code returned from DOMAIN software, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

USAGE 

ERROR _$CODE extracts and returns the module-specific code from the supplied status 
code. The module-specific code is the rightmost 16 bits of a STATUS _$T data type. 

This routine is intended for use by FORTRAN programs that need to check for specific 
status codes. Pascal programs can refer to this component directly. 
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ERROR _$FAIL 

Returns the state of the fail bit of a status code. 

FORMAT 

fail = ERROR_$FAIL (status) 

RETURN VALUE 

fail 

The value of the fail bit of the status code. This is a Boolean (logical) value. 

INPUT PARAMETERS 

status 

A status code returned from DOMAIN software, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

USAGE 

ERROR_$FAIL extracts and returns the value of the fail bit of the supplied status code. 
The fail bit is bit number 31 in the STATUS _$T data type. 

This routine is intended for use by FORTRAN programs that need to check for specific 
status codes. Pascal programs can refer to this component directly. 
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ERROR _ $FIND _TEXT 

ERROR_ $FIND _ TEXT 

Finds the text associated with a status code and returns pointers. 

FORMAT 

ERROR_$FIND_TEXT (status, subsys_p. subsys_l, module_p, module_l, 
code_p. code_l) 

INPUT PARAMETERS 

status 

A status code returned from DOMAIN software, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

OUTPUT PARAMETERS 

subsys_p 

The returned pointer to the subsystem name, in ERROR _$STRING_PTR_T format. 
This is a 4-byte integer. 

subsys_l 

The number of characters in the string pointed to by subsys_p. This is a 2-byte integer. 

module _p 

The returned pointer to the module name, in ERROR_$STRING_PTR_T format. This 
is a 4-byte integer. 

module _1 

The number of characters in the string pointed to by module_p. This is a 2-byte integer. 

code_p 

The returned pointer to the diagnostic text, in ERROR_$STRING_PTR_T format. 
This is a 4-byte integer. 

code_l 

The number of characters in the string pointed to by code _ p. This is a 2-byte integer. 

USAGE 

ERROR _$FIND_ TEXT looks up and returns pointers to the text associated with a status 
code. 

Text is associated with three components of the STATUS _$T type: subsystem name 
("subsys"), module name ("module"), and error text ("code"). If 

ERROR _$FIND_ TEXT cannot find the text associated with a component in the status 
code, a string length of zero is returned for the component. In this case, the pointer for 
that component is not useable. 

If the subsystem text length is zero, the status is invalid. If the module text length is zero, 
both the module and code fields are invalid. 

FORTRAN programs should use ERROR_ $ GET _ TEXT instead of this routine. 
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ERROR_$GET_TEXT ^ 

Finds the text associated with a status code and returns strings. ^- 

FORMAT 

ERROR_$GET_TEXT (status, subsys_t, subsys_l, module_t, module_l, 
code_t, code_l) 

INPUT PARAMETERS 

status 

A status code returned from DOMAIN software, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

OUTPUT PARAMETERS 

subsys_t V 

The text string containing the subsystem name, in ERROR _$STRING_T format. This is 
an array of up to 80 characters. 

subsys_l 

The number of characters in the subsystem name. This is a 2-byte integer. 

module_t 

The text string containing the module name, in ERROR _$ STRING _T format. This is an f 

array of up to 80 characters. \^ 

module _1 

The number of characters in the module name. This is a 2-byte integer. 

code_t 

The text string containing the diagnostic text, in ERROR _$STRING_T format. This is 
an array of up to 80 characters. 

code_l ( 

The number of characters in the diagnostic text. This is a 2-byte integer. 

USAGE 

ERROR _$GET_ TEXT looks up and returns the text associated with a status code. 

Text is associated with three components of the STATUS _$T type: subsystem name 
("subsys"), module name ("module"), and error text ("code"). If ERROR _$GET_ TEXT 
cannot find the text associated with a component in the status code, a string length of zero 
is returned for the component. 

If the subsystem text length is zero, the status is invalid. If the module text length is zero, 
both the module and code fields are invalid. 



The returned strings are not blank-filled. They contain only the number of characters 
necessary to represent the names and diagnostic text. 
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ERROR_ $INIT_ STD _FORMAT 

ERROR _ $INIT _ STD _FORMAT 

Establishes the values to be used in subsequent calls to ERROR _$ STD _ FORMAT. 

FORMAT 

ERROR_$INIT_STD_FORMAT (stream-id, prefix-char, command, length) 

INPUT PARAMETERS 

stream _ id 

The stream on which to write the error output, in STREAM _$ID_T format. This is a 
2-byte integer. This is usually STREAM _$ERROUT (Stream ID = 3). 

prefix- char 

The prefix element of the error format. This is one character. For system messages, this 
value is usually a question mark (?). 

command 

The command name, in ERROR _$STRING_T format. This is an array of up to 80 
characters. 

length 

The length of the command name, in bytes. This value can be zero. 

USAGE 

This call establishes constant values for the standard error reporting format. Subsequent 
calls to ERROR _$ STD _ FORMAT cause error messages to use the values supplied in this 
call. 

Multiple calls may be made to ERROR_$INIT_STD_FORMAT, but the information is 

kept on a per-process-level basis. Thus, successive calls to 

ERROR _$INIT_ STD _ FORMAT on the same process level replace previous error format 

definitions. 

Calling ERROR _$INIT_ STD _ FORMAT and ERROR _$STD_ FORMAT is equivalent 
to calling ERROR_$PRINT_FORMAT. For programs that use common subroutines, the 
former method provides more flexibility. For example, if an application's command level 
sets the command name with ERROR _$INIT_ STD _ FORMAT, it automatically provides 
the common lower-level modules with the correct command name for their error messages. 
Also, because ERROR _$STD_FORMAT has fewer parameters, it is easier to code using 
the pair of calls instead of using ERROR _$PRINT_ FORMAT. 
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ERROR _$MODULE 

Returns the module component from a status code. 

FORMAT 

module = ERROR_$MODULE (status) 

RETURN VALUE 

module 

The module component of the supplied status code. This is a 2-byte integer. 

INPUT PARAMETERS 

status 

A status code returned from DOMAIN software, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

USAGE 

ERROR _$MODULE extracts and returns the module component of the supplied status 
code. The module is found in bits 23 through 16 of the STATUS _$T data type. 

This routine is intended for use by FORTRAN programs that need to check for specific 
status codes. Pascal programs can refer to this component directly. 
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ERROR _$PRINT 

Prints error text associated with a status code. 

FORMAT 

ERROR_$PRINT (status) 

INPUT PARAMETERS 

status 

A status code returned from DOMAIN software, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

USAGE 

ERROR _$PRINT looks up the text associated with the status code and writes it to the 
error output stream. 

If text is associated with all fields in the status code (subsystem, module, and code), a line is 
output containing the subsystem and module names. 

If the text for any of the three fields is not found, the status code is displayed in 
hexadecimal, along with the subsystem and module names, if known. 

The STCODE command, which can be used to view error messages, uses ERROR_$PRINT 
to output the error text. 
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ERROR_$PRINT_FORMAT r 

Prints a status code in the given error format. ^ 

FORMAT 

ERROR_$PRINT_FORMAT (status, stream-id, prefix-char, command, length, 
control-string, al, a2, ... alO) 

INPUT PARAMETERS 

status 

The status code to be displayed in standard error format, in STATUS _$T format. This 
data type is 4 bytes long. See the ERROR Data Types section for more information. 

If the status code is zero, the dash and following error text are omitted from the message. 

stream- id ( 

The stream on which to write the error output, in STREAM _$ED_T format. This is a ^- 

2-byte integer. This value is usually STREAM _$ERROUT (Stream ID + 3). 

prefix- char 

The prefix element of the error format. This is one character. For system error messages, 
this value is usually a question mark (?). 

command 

The command name, in ERROR _$STRING_T format. This is an array of up to 80 ( 

characters. V 

length 

Length of the command name, in bytes. This is a 2-byte integer. If length is zero, the 
command name portion of the standard error format is omitted. 

control- string 

A character string that contains text and control information for encoding the arguments 
that follow. It is a VFMT control string that must at least contain the two special (^ 

characters (%, $). For detailed information on VFMT control strings, see the chapter on V. 

"Formatting Variables with VFMT in Programming With General System Calls. 

al, a2, ... alO 

One-to-ten substitution arguments that contain data for encoding using the control-string 
parameter. 

If you are encoding ASCII text strings, you must provide two variables for each text string: 
a character string containing the string, and a 2-byte integer variable containing the length 
of the string. 
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USAGE 

ERROR _$PRINT_ FORMAT prints an error in the standard error format. 

ERROR _$PRINT_ FORMAT takes a variable number of arguments in the al...alO 
parameters. However, all arguments up to and including the control string must be given. 

This routine uses the same control string format as the variable formatting routine 
VFMT $WRITE. 
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ERROR_$PRINT_NAME 

Prints error text associated with a status code, along with a user-supplied name. 

FORMAT 

ERROR_$PRINT_NAME (status, name, namelength) 

INPUT PARAMETERS 

status 

A status code returned from DOMAIN software, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

name 

The name to be printed. This is an array of up to 80 characters. 

namelength 

The length of the name to be printed, in bytes. This is a 2-byte integer. 

USAGE 

ERROR _$PRINT_ NAME looks up the text associated with the status code and writes it 
to the error output stream, along with the supplied name. 

If text is associated with all fields in the status code (subsystem, module, and code), output 
appears with the supplied name first, followed by a descriptive error message corresponding 
to the status code, followed the subsystem and module names in parentheses. 

If the text for any of the three fields is not found, the status code is displayed in 
hexadecimal, along with the subsystem and module names, if known. The supplied name is 
also displayed, in the form shown above. 
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ERROR_$STD_FORMAT 

ERROR_$STD_FORMAT 

Prints the status code in the standard error format using the values specified in the last call 
to ERROR $INIT STD FORMAT. 



FORMAT 

ERROR_$STD_FORMAT (status, control-string, al. a2, ... alO) 

INPUT PARAMETERS 

status 

The status to be printed in standard error format, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

control-string 

A character string that contains text and control information for encoding the arguments 
that follow. It is a YFMT control string that must at least contain the two special 
characters (%, $). For more information on VFMT control strings, see Chapter 3 of 
Programming With General System Calls. 

al, a2, ... alO 

One-to-ten substitution arguments that contain data for encoding using the control-string 
parameter. 

If you are encoding ASCII text strings, you must provide two variables for each text string: 
a character string containing the string, and a 2-byte integer variable containing the length 
of the string. 

USAGE 

Programs using ERROR _$STD_ FORMAT must first call 

ERROR _$INIT_ STD _ FORMAT to establish constant values for the standard error 

reporting format. 

This routine uses the same control string format as the variable formatting routine 
VFMT $WRITE. 
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ERROR_$SUBSYS 

Returns the subsystem component from a status code. 

FORMAT 

subsys = ERROR_$SUBSYS (status) 

RETURN VALUE 

subsys 

The subsystem component of the supplied status code. This is a two-byte integer. 

INPUT PARAMETERS 

status 

A status code returned from DOMAIN software, in STATUS _$T format. This data type 
is 4 bytes long. See the ERROR Data Types section for more information. 

USAGE 

ERROR _$SUBSYS extracts and returns the subsystem component of the supplied status 
code. The subsystem is found in bits 30 through 24 of the STATUS _$T data type. 

This routine is intended for use by FORTRAN programs that need to check for specific 
status codes. Pascal programs can refer to this component directly. 
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The FPP (Floating Point Package) programming calls perform various operations on floating 
point state. This section describes their data types, call syntax, and error codes. Refer to the 
Introduction at the beginning of this manual for a description of data-type diagrams and call 
syntax format. 
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DATA TYPES 



FPP OP T 



A 2-byte integer. Options available with 
FPP_$CONTOL and FPP_$STATUS. One of 
the following predefined values: 



READ _ OP 

Reads the FP register into the specified 

variable. 

WRITE_OP 

Writes to the FP register from the specified 

variable. 



FPP $SAVE AREA PTR 



FPP $SAVE AREA T 



STATUS $T 



EXCH_OP 

Exchanges the FP register with the specified 

register. 

A 4-byte integer. A pointer to the storage area 
where the floating point state is saved. 

An array of up to 104 bytes. The storage area for 
saving a the floating point state. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 


31 






field name 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 
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subsys 
) The subsystem that encountered the error (bits 



"> 



24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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FPP_$CONTROL 

FPP_$CONTROL 

Reads from or writes to the floating point control register. I 

FORMAT 

FPP_$CONTROL (options, control-reg, status) 

INPUT PARAMETERS 

options 

Specifies the type of action to be taken, in FPP_OP_T format. Specify one of the 
following predefined values: 

READ _ OP Read the FP control register into the variable specified for control-reg. 

WRITE _ OP Write the FP control register from the variable specified for control-reg. 

EXCH_OP Exchange the FP control register with the variable specified for 

control-reg. 

OUTPUT PARAMETERS 

control-reg 

A bit mask of 32 bits, of which only the low 16 bits are currently used. They are 
interpreted as follows: 



t 
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4 3 



PREC 



RND 



Rounding Mode 
00: To nearest 
01: Toward zero 
10: Toward minus infinity 
11: Toward plus infinity 



v Rounding Percision 
00: Extended 
01: Single 
10: Double 
11: Reserved 



Inexact Decimal Input 
Inexact Operation 

Divide by Zero 
Underflow 
Overflow 
Operand Error 
Signalling not a Number 
Branch/Set on Unordered Condition 



status 

Completion status in STATUS _$T format. 
Data Types section for more information. 



This data type is 4 bytes long. See the FPP 



USAGE 



o 



FPP_$CONTROL is used to read from or write to the floating point control register to 
enable/disable various floating point exceptions. This routine is for use only with machines 
equipped with the MC68881 or FPX units. Use of this routine on other machines will result 
in a FPP $UNSUPPORTED FUNCTION error. 
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FPP_$RESTORE 

Restores the floating point state. 

FORMAT 

bytes-restored := FPP_$RESTORE(save-area-ptr, status) 

RETURN VALUE 

bytes- restored 

Number of bytes restored from save area. 

INPUT PARAMETERS 

save- area- ptr 

A pointer to the storage area from which the floating point state is restored. This is a 
4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the FPP 
Data Types section for more information. 

USAGE 

This function returns the number of bytes restored from the specified area. 
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FPP_$SAVE 

FPP_$SAVE 

Saves the floating point state. 

FORMAT 

bytes-saved := FPP_$SAVE(save-area-ptr, status) 

RETURN VALUE 

bytes- saved 

Number of bytes saved in save area. 

INPUT PARAMETERS 

save-area-ptr 

A pointer to the storage area where the floating point state will be saved. This is a 4-byte 
integer. 

OUTPUT PARAMETERS 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the FPP 
Data Types section for more information. 

USAGE 

This function returns to the caller the number of bytes saved in the specified area. 
FPP_$SAVE is useful in fault handlers that implement multitasking environments within 
a single process. 
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FPP _ $SAVE_RESTORE 

Saves current floating point state, then restores the specified floating point state. 

FORMAT 

bytes-moved := FPP_$SAVE_RESTORE(save-area-ptrl, save-area-ptr2, status) 

RETURN VALUE 

bytes- move d 

Number of bytes saved in or restored from save area. 

INPUT PARAMETERS 

save- area- ptrl 

A pointer to the storage area where the current floating point state will be saved. This is a 
4-byte integer. 

INPUT PARAMETERS 

save- area- ptr2 

A pointer to the storage area from which the specified floating point state is to be restored. 
This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the FPP 
Data Types section for more information. 

USAGE 

This function returns the number of bytes saved to or restored from the specified area. ( 
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FPP_$SAVE_RESTORE_SIZE 

Returns the number of bytes required for one state save. 

FORMAT 

save-area-size := FPP_$SAVE_RESTORE_SIZE 

RETURN VALUE 

save-area-size 

Number of bytes required for saving one floating point. 

USAGE 



This function enables the user to determine how many bytes of storage are needed to save 
the floating point state on the particular machine currently executing the function. (The 
number of bytes varies according to the the FP machine type.) It is only necessary to 
specify the returned size amount of space for each state save. 
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FPP_$STATUS 

Reads from or writes to the floating point status register. 

FORMAT 

FPP_$STATUS (options, status-reg, status) 

INPUT PARAMETERS 

options 

Specifies the type of action to be taken, in FPP_OP_T format. Specify one of the 
following predefined values: 

READ _ OP Read the FP status register into the variable specified for status-reg. 

WRITE_OP Write the FP status register from the variable specified for status-reg. 
EXCH_OP Exchange the FP status register with the variable specified for status-reg. 

OUTPUT PARAMETERS 

status-reg 

A bit mask of 32 bits, of which only the low 16 bits are currently used. They are 
interpreted as follows: 



Condition Code Byte 



Quotient Byte 



31 30 29 28 27 26 25 24 23 22 



16 



N 



N 
A 
N 



Quotient 



Seven Least 

Significant Bits of Quotient 



Sign of Quotient 
Not a Number or Unordered 
^ Infinity 
Zero 



Negative 



Reserved 
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Exception Status Byte 



Accrued Exception Byte 



15 14 13 12 11 10 9 8 
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Inexact 
Divide by Zero 
Underflow 
Overflow 



Invalid Operation 
Inexact Decimal input 
Inexact Operation 

Divide by Zero 
Underflow 
Overflow 

Operand Error 
Signalling not a Number 
Branch/Set on Unordered Condition 



status 

Completion status in STATUS _$T format. 
Data Types section for more information. 



This data type is 4 bytes long. See the FPP 



USAGE 
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FPP_$STATUS is used to read from or write to the floating point status register to 
enable/disable various floating point exceptions. This routine is for use only with machines 
equipped with the MC68881 or FPX units. Use of this routine on other machines will result 
in a FPP $UNSUPPORTED FUNCTION error. 
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ERRORS 



FPP _ $INVALID _ OP 

Invalid operation attempted. 

FPP _ $UNSUPPORTED _FUNCTION 

Operation not supported on current hardware. 

STATUS _$OK 

Successful completion. 
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This section describes the data types, the call syntax, and the error codes for the GMF 
programming calls. Refer to the Introduction at the beginning of this manual for a description of 
data type diagrams and call syntax format. 
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DATA TYPES 



GMF $OPOS T 



A 2-byte integer. Specifies the file opening 
positions. One of the following predefined values: 

GMF_ $OVER WRITE 

Provides write access; truncates file to BOF if 

it already exists. 

GMF_$APPEND 

Provides write access if file exists. 



GMF_$MEMORY_T 

GMF_$MEMORY_PTR_T 

STREAM_$ID_T 
STATUS $T 



GMF_$READ 

Provides read access only. 

A 65535-element array of 131070-byte integers. An 
array of two-byte integers. 

A 4-byte integer. A pointer to an array of type 
gmf _ $memory _ t. 

A 2-byte integer. Open stream identifier. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 
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subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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GMF_$CLOSE 

Closes a GMF. 

FORMAT 

GMF_$CLOSE (streamed, status) 

INPUT PARAMETERS 

stream _ id 

The stream ID of the GMF to be closed, in STREAM_$E)_T format. This is a 2-byte 
integer. You obtain the stream ID from the call to GMF_$OPEN that you used to open 
the GMF. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the GPR 
Data Types section for more information. 

USAGE 

To open a GMF, use GMF_$OPEN. 
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GMF_$COPY_PLANE 

GMF _ $COPY_ PLANE 

Dumps a rectangular area of bits from virtual memory into a GMF. 

FORMAT 

GMF_$COPY_PLANE (stream_id, t>lack_or_white, bpi, bit_pointer, x_dim, y_dim, 
width, status) 

INPUT PARAMETERS 

stream _ id 

The stream ID of the GMF into which the image is to be stored, in STREAM_$ID_T 
format. This is a 2-byte integer. You obtain the stream ID from the call to GMF_$OPEN 
that you used to open the GMF. 

black _ or _white 

A Boolean variable. A value of TRUE means "1" bits are black and "0" bits are white. A 
value of FALSE means "1" bits are white and "0" bits are black. In the GMF, "1" bits 
are assumed to mean black. Thus if this parameter is false, the bits will be inverted as they 
are copied. 

bpi 

The number of bits per inch in the GMF. This information is stored in the GMF. It 
indicates the physical density of the image represented in the GMF. If this parameter is 
nonzero, a device to which you output the GMF may compress or expand the image to 
produce a result which is as close as possible to the image's original size. If this parameter 
is zero, an output device uses one dot to represent each bit from the GMF, regardless of the 
resulting physical size of the image. This is a 2-byte integer. 

bit _ pointer 

A pointer to the upper left corner of the rectangular area to be stored, in 
GMF_$MEMORY_PTR_T format. This is a 4-byte integer. You obtain this value by 
calling the routine GPR_ $INQ_ BITMAP _ POINTER. 

"\ x_dim 

The x dimension of the rectangular area to be stored in the GMF. This is a 2-byte integer. 

y_dim 

The y dimension of the rectangular area to be stored in the GMF. This is a 2-byte integer. 

width 

The number of 16-bit words per scan line in the source bitmap. The value of this 
parameter is usually 64. The width must be at least 1/16 of the specified x-dim. For 
instance, if you are storing an area 400 bits wide in a GMF, the source bitmap must use at 
least 25 words to represent each scan line (row of dots). This is a 2-byte integer. You 
obtain this value by calling GPR_$INQ_ BITMAP _ POINTER. 
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GMF_$COPY_PLANE 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the GPR 
Data Types section for more information. 

USAGE 

To store an image in a GMF, you must have opened the GMF with the GMF_$OPEN call. 

After storing an image in a GMF, close the GMF with the GMF_$CLOSE call. 

The GMF _$COPY_ PLANE call is a special case of the GMF_$COPY_SUBPLANE 
call. 
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GMF _ $COPY_ SUBPLANE 

Dumps a rectangular area of bits from virtual memory into a GMF. 

FORMAT 

GMF_$COPY_SUBPLANE (stream_id, t>lac]c_or_white, bpi, bit_pointer, x_dim, y_dim. 
x_offset, y_offset, width, status) 

INPUT PARAMETERS 

stream _ id 

The stream ID of the GMF into which the image is to be stored, in STREAM_$ID_T 
format. This is a 2-byte integer. You obtain the stream ID from the call to GMF _$OPEN 
that you used to open the GMF. 

black _or_ white 

A Boolean variable. A value of TRUE means "1" bits are black and "0" bits are white. A 
value of FALSE means "1" bits are white and "0" bits are black. In the GMF, "1" bits 
are assumed to mean black. Thus if this parameter is false, the bits will be inverted as they 
are copied. 

bpi 

The number of bits per inch in the GMF. This information is stored in the GMF. It 
indicates the physical density of the image represented in the GMF. If this parameter is 
nonzero, a device to which you output the GMF may compress or expand the image to 
produce a result which is as close as possible to the image's original size. If this parameter 
is zero, an output device uses one dot to represent each bit from the GMF, regardless of the 
resulting physical size of the image. This is a 2-byte integer. 

bit _ pointer 

A pointer to a bit which when offset by x_ offset and y_ offset gives the upper left corner 
of the rectangular area to be stored. This is a 4-byte integer. You obtain this value by 
calling the routine GPR_ $INQ_ BITMAP _ POINTER. 

x_dim 

y The x dimension of the rectangular area to be stored in the GMF. This is a 2-byte integer. 

y_dim 

The y dimension of the rectangular area to be stored in the GMF. This is a 2-byte integer. 

x _ offset 

The x starting position of the rectangular area to be stored in the GMF relative to the bit 
whose address is given by bit _ pointer. This is a 2-byte integer. 

y_ offset 

The y starting position of the rectangular area to be stored in the GMF relative to the bit 
whose address is given by bit _ pointer. This is a 2-byte integer. 

width 

The number of 16-bit words per scan line in the source bitmap. The value of this 
parameter is usually 64. The width must be at least 1/16 of the specified x-dim. For 
instance, if you are storing an area 400 bits wide in a GMF, the source bitmap must use at 
least 25 words to represent each scan line (row of dots). This is a 2-byte integer. You 
obtain this value by calling GPR_$INQ_BITMAP_POINTER. 



GMF- 7 GMF 
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OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the GPR 
Data Types section for more information. 

USAGE 

To copy a plane into a GMF, you must have opened the GMF with the GMF_$OPEN call. 

After copying a plane into a GMF, close the GMF with the GMF_$CLOSE call. 

The GMF_$COPY_SUBPLANE call is a more general form of the 
GMF $COPY PLANE call. 
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GMF_$OPEN 

Opens or creates a GMF. 

FORMAT 

GMF_$OPEN (name, name_length, start, streamed, status) 

INPUT PARAMETERS 

name 

Pathname, in NAME_$PNAME_T format. 

name _ length 

The length of the name. This is a 2-byte integer. 

start 

Desired position in the file after open, in GMF_$OPOS_T format. This is a 2-byte 
integer. If you are opening the GMF to write data to it (to copy a plane or subplane into 
it), use one of these two constants: 

GMF_$APPEND sets the initial position to EOF. 

GMF_$ OVERWRITE truncates the object to length and sets the initial 
position to the beginning. 

If you are opening the GMF to read data from it (restoring a plane), use this constant: 

GMF_$READ sets the initial position to the beginning without 

truncating the GMF 



If the specified GMF does not exist and you used GMF_$OPEN to create it, it does not 
matter what value this parameter has. 

OUTPUT PARAMETERS 

stream _ id 

The stream ID of the opened GMF, in STREAM _$ID_T format. This is a 2-byte integer. 
You use this value in subsequent GMF calls that refer to the opened GMF. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the GPR 
Data Types section for more information. 
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USAGE 

If the specified GMF does not exist, the call to GMF_$OPEN creates it. 

You must call GMF_$OPEN before trying to read or write a GMF. 

After opening a GMF with GMF_$OPEN, you must eventually close it by calling 
GMF $CLOSE. 
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GMF _ $RESTORE _ PLANE 

Copies an image back to the screen from a GMF. 

FORMAT 

GMF_$RESTORE_PLANE (stream_id. x_dim, y_dim, width, start, bpi, status) 

INPUT PARAMETERS 

stream _ id 

The stream ID of the GMF which is to supply the image, in STREAM_$ID_T format. 
This is a 2-byte integer. You obtain this parameter from the call to GMF_$OPEN you 
used to open the GMF. 

x_dim 

The x-dimension in bits of the display to which an image is to be restored. This is a 2-byte 
integer. 

y_dim 

The y-dimension in bits of the display to which an image is to be restored. This is a 2-byte 
integer. 

width 

The number of 16-bit words per scanline in the destination bitmap. This is a 2-byte 
integer. 

start 

The starting address in the destination bitmap. In Pascal this is a UNIV_PTR. See the 
GPR Data Types section for more information. 

OUTPUT PARAMETERS 

bpi 

Bits per inch as specified in GMF _$COPY_ PLANE. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the GPR 
Data Types section for more information. 
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USAGE 



Before calling GMF _$RESTORE_ PLANE, you must use GPR_$INIT to place the node 
in borrow-display mode. 

The size of the area to be restored is the same as the size of the area you originally copied 
into the GMF. This information is contained in the GMF. 

The area to be restored is determined by the bit-pointer specified in the 
GMF _$RESTORE_ PLANE call and the size data in the GMF. If this area runs off the 
right side or the bottom of the screen, the GMF manager restores only the portion of the 
stored image that fits on the screen. 

To restore a plane from a GMF, you must have opened the GMF with the GMF_$OPEN 
call. 

After restoring a plane from a GMF, you should close the GMF with the GMF_$CLOSE 
call. 
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ERRORS 

GMF_$BAD_BPI 

Bits/inch parameter is negative. 

GMF_$BAD_POS 

Opening position parameter is illegal. 

GMF_$BAD_WPL 

16 bit words/line parameter is too small for x dim. 

GMF_$BAD_X_DIM 

X-dimension parameter is not positive. 

GMF _ $BAD _ Y_DIM 

Y-dimension parameter is not positive. 

GMF_$NOT_GMF 

Opened file not a GMF metafile. 

STATUS _$OK 

Successful completion. 
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The IOS (I/O Switch) programming calls perform device-independent I/O. This section describes 
their data types, call syntax, and error codes. Refer to the Introduction at the beginning of this 
manual for a description of data-type diagrams and call syntax format. 
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IOS DATA TYPES 



CONSTANTS 



IOS_$MAX 

IOS _$NO_ STREAM 

VARIABLES 

XOID $NIL 



127 Highest possibe number in stream ID. 

16#7FFF Placeholder for stream ID. 



A variable whose value is the NIL XOID and 
doesn't change. Used for comparisons and 
assignments of XOID_$T variables. 



DATA TYPES 



IOS $ABS REL T 



IOS $CONN FLAG T 



A 2-byte integer. Specifies whether seek is relative 
or absolute. One of the following predefined values: 

IOS_$RELATIVE 

Seek from the current position. 

IOS_$ABSOLUTE 

Seek from the beginning of the object (BOF). 

A 2-byte integer. Attributes associated with a 
stream connection. One of the following predefined 
values: 

IOS_$CF_TTY 

Connection behaves like a terminal. 

IOS_$CF_IPC 

Connection behaves like an interprocess 

communication (IPC) channel. 

IOS_$CF_VT 

Connection behaves like a DOMAIN Display 

Manager pad. 

IOS_$CF_WRITE 

Connection can be written to. 

IOS_$CF_APPEND 

Connection's stream marker can be positioned 

to the end of the object before each put call. 

IOS_$CF_UNREGULATED 

Other processes can read and write to the 

connection. 

IOS_$CF_READ_INTEND_WRITE 

Connection open for read access, and can later 



v... 
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\ 



IOS $CONN FLAG SET 



be open for write access. Other processes can 
have read access. 

A 4-byte integer. A set of connection attributes, in 
IOS_$CONN_FLAG_T format, indicating which 
attributes of the specified connection are set. For a 
list of options, see IOS_$CONN_FLAG_T 
above. 



IOS $CREATE MODE T 



A 2-byte integer. Specifies the action to be taken if 
the name already exists or specifies creation of 
umnamed objects. One of the following predefined 
values: 



IOS_$LOC_NAME_ONLY_MODE 
Create a temporary unnamed object, uses 
pathname to specify location of object, and 
locates it on the same volume. 

IOS _ $MAKE_BACKUP _MODE 

Create a backup (.bak) object when closed. 



IOS_$NO_PRE_EXIST_MODE 

Return an error if object already exists. 



IOS_$PRESERVE_MODE 
Save contents of object, if it exists, opens 
object, and positions stream marker at the 
beginning of the object (BOF). 



IOS_$RECREATE_MODE 

Delete existing object and creates new one of 

same name. 



IOS $DIR TYPE T 



IOS_$TRUNCATE_MODE 

Open object, then truncates the contents. 

A 2-byte integer. Specifies type of directory. One 
of the following predefined values: 



IOS_$WDIR 

Current working directory. 



IOS SEC KEY T 



IOS_$NDIR 

Current naming directory 

A 2-byte integer. Specifies eventcount key type. 
One of the following predefined values: 



IOS_$GET_EC_KEY 

Key that is advanced with each get call. 



IOS_$PUT_EC_KEY 

Key that is advanced with each put call. 
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IOS_$ED_T A 2-byte integer, ranging in value from to 

IOS_$MAX. The stream ID. 

IOS_$MGR_FLAG_T A 2-byte integer. Object attributes associated with 

an object's manager. One of the following 
predefined values: 

IOS_$MF_CREATE 

Manager permits type to create objects. 

IOS_$MF_CREATE_BAK 

Manager permits type to create backup (.bak) 

objects. 

IOS_$MF_IMEX 

Manager permits type to export streams to 

new processes. 

IOS_$MF_FORK 

Manager permits type to pass streams to 

forked processes. 

IOS_$MF_FORCE_WRITE 
Manager permits type to force- write object 
contents to stable storage (for most object 
types, this is the disk). 

IOS_$MF_WRITE 

Manager permits objects to be written to. 

IOS_$MF_SEEK_ABS 

Manager permits objects to perform absolute 

seeks. 

IOS_$MF_SEEK_SHORT 

Manager permits objects to seek using short 

(4-byte) seek keys. 

IOS_$MF_SEEK_FULL 

Manager permits objects to seek using full 

(8-byte) seek keys. 

IOS_$MF_SEEK_BYTE 

Manager permits objects to seek to byte 

positions. 

IOS_$MF_SEEK_REC 

Manager permits objects to seek to record 

positions. 

IOS_$MF_SEEK_BOF 

Manager permits objects to seek to the 

beginning of the object. 

IOS $MF REC TYPE V 
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Manager supports different record type 
formats. 

IOS _$MF_ TRUNCATE 

Manager permits objects to be truncated. 

IOS_$MF_UNREGULATED 

Manager permits objects to have shared 

(unregulated) concurrency mode. 

IOS_$MF_SPARSE 

Manager permits objects to be as sparse. 

IOS _$MF_READ _INTEND _ WRITE 
Manager permits objects to have 
read-intend-write access. 



o 



IOS $MGR FLAG SET 



IOS $NAME TYPE T 



A 4-byte integer. A set of object manager 
attributes, in IOS_$MGR_FLAG_T format, 
indicating which attributes of the specified object's 
manager are set. For a list of options, see 
IOS_$MGR_FLAG_T above. 

A 2-byte integer. Specifies format of pathname. 
One of the following predefined values: 



o 



IOS_$ROOT_NAME 

Absolute pathname relative to the network 

root directory (//); for example, 

//node/sid/file. 

IOS _$WDIR_ NAME 

Leaf name if object's name is a name in 
current working directory; otherwise, specifies 
absolute pathname. 

IOS_$NDIR_NAME 

Leaf name if object's name is a name in 
current naming directory; otherwise, specifies 
absolute pathname. 



IOS_$NODE_NAME 

Name relative to the node's entry directory 
(/) if object is a name in boot volume; 
otherwise, specifies absolute pathname; for 
example, /sid/file. 

IOS_$NODE_DATA_FLAG 
Leaf name if object's name is a name in 
current 'node _ data directory; otherwise, 
specifies absolute pathname. 



IOS _$LEAF_ NAME 

Leaf name regardless of object's name. 
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IOS_$RESID_NAME 

Residual name if object is defined using 

extended naming. 



IOS_$OBJ_FLAG_T A 2-byte integer. Attributes associated with an 

object. One of the following predefined values: 

IOS _$OF_DELETE_ON_ CLOSE 

Object can be deleted when all its associated 

connections are closed. 

IOS_$OF_SPARSE_OK 

Object can be written as a sparse object. 

IOS_$OF_ASCII 

Object contains ASCII data. 

IOS_$OF_FTNCC 

Object uses FORTRAN carriage control 

characters. 

IOS_$OF_COND 

Object performs get or put calls conditionally, 

as if the IOS_$COND_OPT was specified. 

IOS_$OBJ_FLAG_SET A 4-byte integer. A set of object attributes, in 

IOS_$OBJ_FLAG_T format, indicating which 
attributes of the specified object are set. For a list 
of options, see IOS_$OBJ_FLAG_T above. 

IOS _$OPEN_ OPTIONS _T A 2-byte integer. Specifies options for an 

IOS_$OPEN. Any combination of the following 
predefined values: 

IOS_$NO_OPEN_DELAY_OPT 

Return immediately instead of waiting for 

open to complete. 

IOS_$WRITE_OPT 

Permit writing data to a new object. 

IOS _ $UNREGULATED _ OPT 

Permit concurrency (unregulated read and 

write access.) to the object 

IOS_$POSITION_TO_EOF_OPT 

Position stream marker to the end of the 

object at open. 

IOS_ $INQUIRE_ ONLY_ OPT 

Open object for attribute inquiries only. 

IOS_ $READ _ INTEND _ WRITE_ OPT 
Object has read-intend-write access, other 
processes can have read but not write access. 
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IOS $POS OPT T 



A 2-byte integer. Specify position to return when 
inquiring about object position. One of the 
following predefined values: 



IOS _$ CURRENT 

Return key for the current stream marker. 

IOS_$BOF 

Return key for beginning of the object (BOF) 

marker. 

IOS_$EOF 

Return key for end of the object (EOF) 

marker. 



IOS $PUT GET OPTS T 



O 



A 2-byte integer. Specifies options for put and get 
operations. Any combination of the following 
predefined values: 

IOS_$COND_OPT 

Read or write data conditionally. If call fails, 

returns 

IOS _ $xxx_ CONDITIONAL _FAILED, 

where xxx is either GET or PUT. 



o 



IOS_$PREVIEW_OPT 

Write data but do not update the stream 

marker. 

IOS_$PARTIAL_RECORD_OPT 

Write a portion of a record but do not 

terminate it. 



O 



IOS $RTYPE T 



IOS_$NO_REC_BNDRY_OPT 
Ignore record (line) boundries. 

A 2-byte integer. Specifies the record type format. 
One of the following predefined values: 



IOS_$Vl 

Variable-length record with count fields. 

IOS_$F2 

Fixed-length records with count fields. 

IOS_$UNDEF 

No record structure. 

IOS_$EXPLICIT_F2 

Fixed-length records that IOS_$PUT cannot 

implicitly change to IOS_$Vl. 



A 



IOS_$Fl 

Fixed-length records without count fields. 
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IOS_$SEEK_KEY_T 
IOS $SEEK TYPE T 



STATUS $T 



The full seek key. This is an 8-byte integer value. 

A 2-byte integer. Specifies the type of seek to 
perform. One of the following predefined values: 

IOS _$REC_ SEEK 
Record-oriented seek. 

IOS _$BYTE_ SEEK 
Byte-oriented seek. 

A status code. The diagram" below illustrates the 
STATUS _$T data type: 



byte: 
offset 



31 



field name 



0: 


integer 


all 


0: 


" 31 


or 

| 24 
I 





fail 






subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 



fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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UID $T 



XOID $T 



An object type identifier. This is an 8-byte integer 
value. 

Unique identifier of an object. Used by type 
managers only. The diagram below illustrates the 
XOID_$T datatype: 



o 



o 



predefined 
type 


byte: 
offset 

0: 

4: 

8: 

12: 


31 





field name 




integer 


rful 




integer 


rfu2 


uid_$t 


integer 


UID 




integer 








Field Description 










rful 








Reserved for future use. 








rfu2 








Reserved for future use. 








UID 








Unique identifier for an object 
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IOS_$CHANGE_PATH_NAME 

IOS_$CHANGE_PATH_NAME 

Changes the pathname of an object. v — s 

FORMAT 

IOS_$CHANGE_PATH_NAME (stream-id, new-pathname, new-namelength, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

new- pathname 

New name of the object, in NAME_$PNAME_T format. This is an array of up to 256 

new-namelength V s 

Length of "new-pathname." This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 

Data Types section for more information. / N 

USAGE 

IOS _$CHANGE_ PATH _ NAME changes the pathname of an existing object. The 
stream ID of the object remains the same. 

IOS _$ CHANGE _ PATH _ NAME permits you to assign a name to a previously unnamed 

object and, conversely, to remove a name from a previously named object. (To remove a 

name, specify a null pathname.) [ 

Note that this call can change the delete-on-close object attribute. For example, if you 
assign a name to an unnamed object, the operation implicitly changes the delete-on-close 
attribute to FALSE. Likewise, if you specify a null pathname for a previously named 
object, the operation implicitly changes the delete-on-close attribute to TRUE. Be aware 
that this behavior can cause unexpected results in cases where you explicitly change the 
delete-on-close attribute, and then make an unnamed-to-named name change. 
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IOS_$CLOSE 

Closes a stream. 

FORMAT 

IOS_$CLOSE (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream to be closed, in IOS_$ID_T format. This is a 2-byte integer. 

Once IOS_$CLOSE closes the stream, the number used for this stream ID becomes 
available for reuse. If the object is open on more than one stream, IOS_$CLOSE closes 
only "stream-id." 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

IOS_$CLOSE closes the stream so that you can no longer use the stream ID to operate on 
the object. Closing a stream to an object releases any locks maintained by the stream 
connection, thus making the object available to other users. 

A program can close only the streams that it has opened at the current or lower program 
levels (that is, streams opened by programs that the calling program has invoked). 
IOS _ $CLOSE returns an error status code if you try to close a stream that was opened at 
a higher program level. 

If an object has the delete-on-close attribute (IOS_$OF_DELETE_ON_CLOSE), 
IOS_$CLOSE deletes the object. However, the object is not deleted until all streams to it 
are closed. (For details on object attributes, see the IOS_$INQ_$OBJ_FLAGS and 
IOS_$SET_OBJ_FLAG calls.) 
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IOS_$CREATE 

Creates an object and opens a stream to it. 



- y 



FORMAT 

IOS_$CREATE (pathname, namelength, type-uid, create-options, 
open-options, stream-id, status) 

INPUT PARAMETERS 

pathname 

Name of the object to be created, in NAME_$PNAME_T format. This is an array of up 
to 256 characters. To create a temporary object, see the section "Creating an Object in 
Backup Mode" below. 

namelength 

Length of "pathname," in bytes. This is a 2-byte integer. To create a temporary object, 
see the section "Creating an Object in Backup Mode" below. 

type-uid 

UID of the type to be created, in UID_$T format. This data type is 8 bytes long. See the 
IOS Data Types section for more information. 

If you specify the predefined UH)_$NIL, IOS_$CREATE creates an object of the default 
type, which is currently unstructured ASCII (UASC). You can also specify any of the 
system's predefined type UDDs listed below, or any valid user-created type UID. 

DOMAIN currently supports a set of standard object types which include the following 
types. (Note that objects created by type managers return manager-specific type UEDs.) 



Type UID 

UASC_$UID 

RECORDS _$UID 

HDR_UNDEF_$UH> 

OBJECT_FILE_$UID 

SIO_$UID 

MT_$UID 

PAD_$UID 

INPUT _PAD_$UID 

MBX $UID 



Object 

UASC object 

Record-oriented object 

Nonrecord-oriented object 

Object module object (compiler or binder output) 

Serial line descriptor object 

Magnetic tape descriptor object 

Saved Display Manager transcript pad 

Display Manager input pad 

Mailbox object 
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Type UK) 



DIRECTORY $UE) 



Object 

Directory 



NULLDEV $UID 



Null device 



create- options 

Specifies the action to be taken if the object already exists, or specifies the creation of an 
unnamed object, in IOS _$ CREATE _ MODE _T format. This is a 2-byte integer. Specify 
one of the following predefined values: 



IOS $NO PRE EXIST MODE 



Return the IOS_$ALREADY_EXISTS error 
status code if an object with the specified 
name already exists. 



IOS $PRESERVE MODE 



Preserve the contents of the object if an 
object with the specified name already exists. 
Then open the object and position the stream 
marker to the beginning of the object (BOF) 
unless you set the 

IOS_$POSITION_TO_EOF open option. 
Use this mode to append data to an existing 
object. 



IOS $RECREATE MODE 



Recreate the object if an object with the 
specified name already exists. Essentially, this 
option deletes the existing object and creates a 
new one. The new object will have the default 
set of attributes for that object type. 



IOS $TRUNCATE MODE 



o 



IOS $MAKE BACKUP MODE 



IOS $LOC NAME ONLY MODE 



Open the object and delete the contents if an 
object with the specified name already exists. 
Use this mode to create an object to preserve 
the attributes of the specified object. 

Create a temporary object with the same type 
and attributes as the object specified in the 
pathname if an object with the specified name 
already exists. Use this mode to create a 
backup object. (See below for detailed 
description.) 

Create a temporary unnamed object. Use the 
pathname to specify the location of the object. 
IOS_$CREATE will locate the temporary 
object on the same volume as the object 
specified in the pathname. 
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open- options 

Open options, in IOS _$OPEN_ OPTIONS _T format. This is a 2-byte integer. Specify a 
combination of the following set of predefined values: 



IOS $NO OPEN DELAY OPT 



IOS $WRITE OPT 



IOS $UNREGULATED OPT 



Return immediately, instead of waiting for the 
open call to complete. 

Permit writing data to a new object. If a 
program tries to write on a stream for which 
you have not specified this option, it returns 
an error status. Note that when creating an 
object, the IOS manager automatically sets 
this value because it assumes that when you 
create an object, you will want to write to it. 

Permit shared (unregulated) concurrency 
mode. 



\._V 



IOS $POSITION TO EOF OPT 



IOS _ $INQUIRE _ ONLY_ OPT 



IOS $READ INTEND WRITE OPT 



Position the stream marker at the end of the 
object (EOF). Use this to append data to an 
existing object. 

Open the object for attribute inquiries only; 
do not permit reading or writing of data. 

Open the object for read access with the 
intent to eventually change the object's access 
to write access. This allows other processes to 
read the object; but they cannot have write or 
read-intend-write access. 



OUTPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

Subsequent IOS calls use this number to identify the stream opened by this call. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 
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IOS- 14 



IOS $CREATE 



USAGE 



V. 



If the pathname specifies an object that does not exist, IOS_$CREATE creates a new 
object of the specified type using that pathname and opens a stream to it. If the object 
already exists, the create mode option specified in the call determines which action 
IOS_$CREATE will perform. 

Both IOS_$OREATE and IOS_$OPEN open a stream to an object. However, 
IOS_$CREATE creates the object if it does not exist, whereas IOS_$OPEN returns an 
error if the object does not exist. 

Inquiring about Object Attributes 

When IOS_$CREATE creates an object, the object has a default set of attributes (the 
default attributes depend on the type created). These attributes fall into three categories: 
manager, object, and connection attributes. To determine which attributes the newly 
created object has, you can use the following calls: 

IOS _$INQ_MGR_ FLAGS 

Returns the attributes that the object's type manager defines. 

IOS _ $INQ _ OB J_FLAGS 

Returns the attributes of the object. 

IOS_$INQ_CONN_FLAGS 

Returns the attributes of the stream connection. 

To change object or connection attributes, use the IOS_$SET_OBJ_FLAGS, and 
IOS _$SET_ CONN _ FLAGS calls, respectively. The attributes that you can change 
depend on the object type. Note that you cannot change manager attributes because the 
type manager determines them. For details on writing a type manager, see the Extending 
the DOMAIN Streams Facility manual. 

Creating a Temporary Object 

IOS_$CREATE allows you to create a temporary object two ways. To create a temporary 
object on your boot volume, specify a null value in "pathname" and a value of in 
"namelength." To create a temporary object on another volume, specify the pathname of 
an existing object on that volume with the IOS _$LOC_ NAME _ONLY_MODE option in 
"create-options." IOS_$CREATE creates a temporary unnamed object on the same 
volume (node) as the object you specify in "pathname." 

Creating an Object in Backup Mode 

You can create a new, unnamed temporary object by specifying the create mode option, 
IOS_$MAKE_BACKUP_MODE. The call creates the new object with the same type and 
attributes as the object specified by "pathname" (if it exists), and it is created on the same 
volume (node). 

IOS_$CREATE does not open or modify the object specified by "pathname," it merely 
examines the object to extract its attributes. Even though IOS_$CREATE does not 
modify the "pathname," it conceptually replaces the object, so this operation requires write 
access to the object. 
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When IOS_$CLOSE closes the stream created with this call, it changes the object specified 
by "pathname" to "pathname.bak." It changes the new object (formerly the temporary, 
unamed object) to "pathname," and makes the object permanent. 

If a ".bak" version of the object already exists, IOS_$CLOSE deletes it. (The caller must 
have either D or P rights to delete the object.) If the ".bak" object is locked at the time 
IOS_$CLOSE is called, the object will be deleted when it is unlocked. 

If "pathname" does not exist at the time that IOS_$CREATE is called, then 
IOS_$CREATE performs the ordinary functions. 
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IOS_$DELETE 

Deletes an object and closes the associated stream. 

FORMAT 

IOS_$DELETE (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in IOS_$ID_T format. This is a 2-byte 
integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

IOS_$DELETE deletes the object, then closes the specified stream. 

This call actually sets the object attribute IOS_$OF_DELETE_ON_CLOSE to TRUE, 
then closes the stream. So, if the type manager does not allow an object to set the 
delete-on-close attribute, the delete call fails. In this case, the call closes the stream, but 
does not delete the object. 

If the object is open on more than one stream, IOS_$DELETE marks the object for 
deletion, but the object still exists until all streams to that object are closed. 
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IOS_$DUP 

Creates a copy of a specified stream ID. 

FORMAT 

return_stream_id = IOS_$DUP (stream_id_to_duplicate, copy_stream_id, status) 

RETURN VALUE 

return _ stream _ id 

Number of the new stream created, in IOS_$ID_T format. This is a 2-byte integer. 

INPUT PARAMETERS 

stream _ id _to_ duplicate 

Number of the stream to duplicate, in IOS_$ID_T format. This is a 2-byte integer. This 
stream number remains a valid connection to the object after IOS_$DUP completes 
successfully. 

copy _ stream _ id 

Number of the stream to use as the newly created copy, in IOS_$ID__T format. This is a 
2-byte integer. 

If " copy _ stream _ id" is free, IOS_$DUP returns that value in " return _ stream _ id." If 
" copy _ stream _ id" is in use, IOS_$DUP begins searching from that number upward 
(higher numbers) until it finds a free stream number and returns that number in 
" return _ stream _ id." 

If the actual number of " copy _ stream _ id" is insignificant, specify the value 0. This value 
causes IOS_$DUP to begin searching from the lowest possible stream number and return 
the first free stream number it finds. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS_$DUP to create a copy of an existing stream ID. The new stream ID refers to the 
same connection as the existing stream ID. Note that you must close both streams with 
IOS_$CLOSE before the stream connection actually closes. 

You can use IOS_$DUP to keep a stream connection open when passing it to a subroutine. 
Use IOS_$DUP to create a copy of the stream ID before passing it. This way, the 
subroutine cannot close the connection to the object because all copies of the stream 
connection must be closed before the connection itself closes. 
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IOS_$DUP is identical to IOS _ $REPLICATE except that IOS_$DUP looks for a free 
stream number in ascending order from the specified stream ID, while IOS_$REPLICATE 
looks in descending order. Note that you use IOS_$DUP or IOS _ $REPLICATE to copy 
existing stream ID's, both the existing and new stream ID's remain valid connections. 
However, you use IOS_$SWITCH to replace stream IDs; you "switch" the connection from 
the existing stream ID to the new stream ID. 



O 
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IOS_$EQUAL 

Determines whether two stream IDs refer to the same object. 

FORMAT 

same IOS_$EQUAL (stream_id, stream_id_too, status) 

RETURN VALUE 

same 

Boolean value that indicates whether the specified stream IDs refer to the same object. 
"Same" is TRUE if the streams refer to the same object, it is FALSE if they do not. 

INPUT PARAMETERS 

stream _ id 

Number of a stream being compared, in IOS_$ID_T format. This is a 2-byte integer. 

stream _ id _ too 

Number of a stream being compared, in IOS_$ID_T format. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS_$EQUAL to determine whether two stream IDs refer to the same object. An 
application program can use this call to avoid using two streams when one is sufficient. 
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IOS_$FORCE_WRITE_FILE 

Forcibly writes an object to permanent storage. 

FORMAT 

IOS_$FORCE_WRITE_FILE (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 



USAGE 

IOS _$FORCE_ WRITE _ FILE forcibly writes the object to stable storage. Stable storage 
depends on the object's type, however, in most cases, it is the disk. For example, stable 
storage for a magnetic tape descriptor is the tape. 

Use IOS _$FORCE_ WRITE _ FILE before closing the stream to ensure that the object is 
stored safely in the event of a system crash. 
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IOS_$GET 

Moves data from a stream into a buffer. 

FORMAT 

ret-length = IOS_$GET (stream-id, get-options, buffer, buffer-size, status) 

RETURN VALUE 

ret-length 

Amount of data moved, in bytes. This is a 4-byte integer. 

"Ret-length" equals the amount of data read; "ret-length" equals if IOS_$GET does not 
return any data. 

If the length of the data read exceeds the amount specified in "data-size," IOS_$GET 
performs the following: 

• Reads enough data to fill the requested size 

• Sets "ret-length" equal to "data-size" 

• Positions the stream marker to the first unread byte 

• Returns the IOS_$BUFFER_ TOO _ SMALL status code to indicate that this 

condition has occurred /' 



You can inquire about how many bytes remain to be read in the current record by calling 
IOS _ $INQ _REC_REMAINDER. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

get- options 

Options that control how IOS_$GET performs the get operation, in 

IOS _ $PUT_ GET _ OPTS _T format. This is a 2-byte integer. Specify a combination of 

the following set of predefined values: 

IOS_$COND_OPT Reads data, if available. (For example, data 

on an SIO line is not always available 
immediately.) If the data is not available, 
IOS_$GET returns the 
IOS _ $GET _ CONDITIONAL _FAILED 
status code and sets the return value of 
"ret-length" to 0. 

IOS_$PREVIEW_OPT Reads data but does not update the stream 

marker. 
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IOS_$NO_REC_BNDRY_OPT Ignores record boundaries while reading data. 

For example, it ignores NEWLINE characters 
in a UASC object, which guarantees that the 
call fills the specified buffer. Some type 
managers might not support this option. 

IOS_$PARTIAL_ RECORD _ OPT Not meaningful for this call. 

buffer- size 

Maximum number of bytes to be moved to the buffer. This is a 4-byte integer. 

OUTPUT PARAMETERS 

buffer 

Buffer to store the data. This is a character array. 

O status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

You can use either of IOS_$LOCATE or IOS_$GET to read data from system objects. 
IOS_$GET copies the data into a buffer, while IOS_$LOCATE returns the virtual 
address of the data. 

In most cases, use the IOS_$LOCATE call to read data because it is faster 
(IOS_$LOCATE does not perform a copy). 

You will want to use IOS_$GET when you need to read more data than can be obtained in 
one call, because the pointer remains valid for only one call. For example, use IOS_$GET 
when you need to read and rearrange a number of lines from an object. 
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IOS_$GET_DIR 

Gets the current working or naming directory. 

FORMAT 

IOS_$GET_DIR (pathname, name length, dir_type, status) 

INPUT PARAMETERS 

dir_type 

Option specifying which type of directory to get, in IOS_$DIR_TYPE_T format. 
Specify one of the predefined values: 

IOS_$WDIR Name of the current working directory. 
IOS_$NDIR Name of the current naming directory. 

OUTPUT PARAMETERS 

pathname 

Name of the directory to get, in NAME_$PNAME_T format. This is an array of up to 
256 characters. 

namelength 

Length of "pathname." This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use this call to get the current working or naming directory. It returns the name of the 
directory in the "pathname" parameter. If you want to change the current working or 
naming directory, use IOS_$SET_DIR. 
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IOS_$GET_EC 

Gets a pointer to an eventcount for a stream event. 

FORMAT 

IOS_$GET_EC (stream-id, stream-key, eventcount-pointer, status) 

INPUT PARAMETERS 

stream- id 

Number of stream on which the eventcount is waiting, in IOS_$ID_T format. This is a 
2-byte integer. 

stream- key 

The key that specifies which type of eventcount to get a pointer to, in IOS_$EC_KEY_T 
format. This is a 2-byte integer. Specify one of the following predefined values: 

IOS_$GET_REC_EC_KEY An eventcount that advances when the stream 

contains data for you to get. This eventcount 
advances whenever there is anything to get from an 
open stream. 

IOS_$PUT_REC_EC_KEY An eventcount that advances when a previously 

"full" stream might now be able to accept data. A 
full stream is a stream that IOS_$PUT will block. 

OUTPUT PARAMETERS 

eventcount- pointer 

A pointer to the eventcount, in EC2_$PTR_T format. This is a 4-byte integer address 
that points to an array of eventcounts. See the EC2 Data Types section for more 
information. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

IOS_$GET_EC is valid for all streams, including those open to objects, pads, mailboxes, 
and devices. After you use this call to get a stream event, use EC2 calls to read eventcount 
values and wait for events. 

You can wait for two types of events on a stream: 

• The IOS-get eventcount indicates that there might be input to get from an open 
stream. 

• The IOS-put eventcount indicates that a previously "full," or blocked, stream 
might now have enough room to accept the data. 

An example of using the IOS-get eventcount is to wait for keyboard input. Whenever the 
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user types data, the system advances the eventcount associated with the user's input pad. If 
input pad is in normal (or cooked) mode, the eventcount advances after each carriage 
return, if the input pad is in raw mode, the eventcount advances after each keystroke. (For 
details on cooked and raw mode, see the Display Manager chapter in the Programming 
with General System Calls manual.) 

An example of using the IOS-put eventcount is to wait on an MBX channel that might get 
blocked. That is, IOS_$PUT blocks streams associated with MBX channels if a server is 
not ready for the data from the channel. When it's possible to write data without blocking, 
the system advances the IOS-put eventcount. 

For more information on eventcounts, see the Programming with General System Calls 
and the Programming with System Calls for Interprocess Communication manuals. 
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IOS_$GET_HANDLE 

Converts a stream ID to a handle pointer. 

FORMAT 

handle = IOS_$GET_HANDLE (stream-id, type-uid, status) 

RETURN VALUE 

handle 

Pointer to the handle associated with the stream connection, in UNIV_PTR format. This is 
a 4-byte integer. 

INPUT PARAMETERS 

stream- id 

Number of the stream that identifies an open stream, in IOS_$ID_T format. This is a 
2-byte integer. 

type-uid 

Type UID of the object that the type manager handles, in UID_$T format. Specify the 
type UID of the manager you are writing. This data type is 8 bytes long. See the IOS Data 
Types section for more information. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

NOTE: This call is generally of interest to type manager writers only. 

Type manager writers use this call to access an object when implementing an operation that 
is not predefined by the system. When the type manager implements such an operation, it 
is referred to as a direct manager call because the I/O switch does not route the call 
between the client call and the manager. Without switching, the manager receives a stream 
ID from a client. To access the object, the manager must then call IOS _$GET_ HANDLE 
to obtain the object handle associated with the stream ID. 

IOS _$GET_ HANDLE returns an error if the stream ID is not associated with an object of 
the type UID specified by "type_uid." Specify the type UID of the manager you are 
writing so that the manager can be sure it has a stream to an object of its type. 

See the Using the Open System Toolkit to Extend the Streams Facility manual for more 
information. 
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IOS_$INQ_BYTE_POS 

Returns the byte position of the stream marker. 

FORMAT 

byte-position = IOS_$INQ_BYTE_POS (stream-id, position-option, status) 

RETURN VALUE 

byte-position 

Byte position of the stream marker. This is a 4-byte integer. Note that byte positions are 
zero-based; consequently the byte position of the beginning of an object (BOF) is 0. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

position- option 

Value specifying the byte position to return, in IOS_$POS_OPT__T format. This is a 
2-byte integer. Specify one of the following predefined values: 

IOS_$CURRENT Returns the byte position of the current stream marker. 

IOS_$EOF Returns the byte position of the stream marker at the end of 

the object (EOF). This is the number of bytes in the object. 

IOS_$BOF Return the byte position of the stream marker at the beginning 

of the object (BOF). This value is always 0. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

To obtain the offset of the stream marker, use IOS_$INQ_BYTE_POS. (Use 
IOS_$INQ_REC_POS if your object is record-oriented.) 

To get the offset of the stream marker at the beginning or end of the object, specify 
IOS_$BOF or IOS_$EOF, in the "position-option" parameter. Specify 
IOS_$CURRENT to get the offset of the stream marker from the beginning of the object. 
Once you have the returned offset, you can move the stream marker to desired location by 
calling IOS _$SEEK. 

This call allows you to perform a nonkeyed seek by specifying an absolute byte position, or 
by getting an offset from an absolute position, and moving the stream marker to it. 
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Whether you perform a nonkeyed or keyed seek depends on how the object's data is 
represented. For example, programs that need to perform "arithmetic" on the data (such 
as comparing two positions) will use nonkeyed seek operations. Programs that require only 
the ability to move from one position to another in an object will use keyed seek operations. 
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IOS _ $INQ _ CONN _FLAGS 

Returns the attributes associated with a connection. 
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FORMAT 

conn_flags = IOS_$INQ_CONN_FLAGS (stream-id. status) 

RETURN VALUE 

conn _ flags 

A set (bit mask) indicating which attributes of the specified connection are set, in 
IOS_$CONN_FLAG_SET format. This is a 4-byte integer. Any combination of the 
following set of predefined values, in IOS _$CONN_ FLAG _T format, can be returned. If 
the set contains the value, the connection has the attribute. 



IOS_$CF_TTY 
IOS_$CF_IPC 

IOS_$CF_VT 

IOS _$CF_ WRITE 
IOS _$CF_ APPEND 

IOS _ $CF _ UNREGULATED 

IOS $CF READ INTEND WRITE 



Connection behaves like a terminal. 

Connection behaves like an interprocess 
communication (IPC) channel. 

Connection behaves like a DOMAIN Display 
Manager pad. 

Connection can be written to. 

Connection's stream marker will be positioned 
at the end of the object (EOF) before each put 
call. 

Connection is open for unregulated (shared) 
concurrency mode. 

Connection is open for read access, and can be 
changed to write access. Other connections 
can have read access, but not write or 
read-intend- write access. 



INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 
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USAGE 

Use this call to determine which connection attributes are in effect for the specified stream. 

To change object or connection attributes, use the IOS_$SET_OBJ_FLAGS, and 

IOS _$SET_ CONN _ FLAGS calls respectively. Which attributes you can change depends 

on the object type. 
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IOS_$INQ_CUR_REC_LEN 

Returns the length of the record at the current stream marker. 

FORMAT 

rec-length = IOS_$INQ_CUR_REC_LEN (stream-id. status) 

RETURN VALUE 

rec-length 

Length of the current record. This is a 4-byte integer. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS_$INQ_CUR_REC_LEN to determine the length of the record at the current 
stream marker of the specified stream. 

The object specified must be record-oriented (for example, RECORDS _$UID); otherwise, 
IOS_$INQ_CUR_REC_LEN returns an error. 
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Returns object usage attributes including date and time created, date and time last used, 
date and time last modified, number of blocks in the object. 

FORMAT 

IOS_$INQ_FILE_ATTR (stream_id, dt-created, dt-modif ied, dt-used, blocks, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

dt-created 

Date and time the object was created, in TIME_$CLOCKH_T format. This is a 4-byte 
integer. 

dt- modified 

Date and time the object was last modified, in TIME_$CLOCKH_T format. This is a 
4-byte integer. 

dt-used 

Date and time the object was last used, in TIME_$CLOCKH_T format. This is a 4-byte 
integer. 

blocks 

The number of 1024-byte blocks that the object occupies. This is a 4-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS _$INQ_FILE_ ATTR to obtain a time stamp for an object and to determine the 
amount of space that an object occupies. 
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IOS_$INQ_FULL_KEY 
Returns a full seek key. 

FORMAT 

IOS_$INQ_FULL_KEY (stream-id, position-option, full-key, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID__T format. This is a 
2- byte integer. 

position- option 

Value specifying the position to return a full seek key for, in IOS_$POS_OPT_T format. 
This is a 2-byte integer. Specify only one of the following predefined values: 

IOS_$CURRENT Return the full seek key of the current marker. 

IOS_$EOF Return the full seek key of the end of the object (EOF) marker. 

IOS_$BOF Return the full seek key of the beginning of the object (BOF) 

marker. 

OUTPUT PARAMETERS 

full- key 

Full seek key to be used in subsequent seeks, in IOS_$SEEK_KEY_T format. This data 
type is 8 bytes long. See the IOS Data Types section for more information. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

IOS _ $INQ_ FULL _ KEY returns a seek key based on the position option you specify, the 
current stream marker position, beginning or end of the object. 

Use seek keys to perform random access of data. Typically, you use this call to inquire 
about a seek key before writing some data, and then store the seek key. To access the data 
at a later point in time, position the stream marker by calling the 

IOS _$SEEK_ FULL _ KEY call with the stored seek key, and get the data with an IOS get 
operation (IOS_$GET or IOS_$LOCATE). 

Use seek keys merely as an index — do not rely on the contents of the keys. The contents of 
seek keys remain private to the IOS manager, which guarantees only that the seek key 
returns to the position it describes. 

Some object types support seek key positioning, but do not support record or byte 
positioning. Use seek keys for repositioning if your application does not need the 
"arithmetic" properties of record- or byte-positioning (that is, the ability to compute 
positions given positions). 
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The DOMAIN system offers both short (4-byte) and full (8-byte) seek keys. Because short 
seek keys require half the storage space of full seek keys, you might want to use short seek 
keys if your application program stores a large number of seek keys. However, short seek 
keys are limiting in that you can only indicate record boundary positions, while full seek 
keys allow you to indicate any position. 
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IOS_$INQ_MGR_FLAGS 

Returns the attribute set of an object's manager. 
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FORMAT 

mgr_flags = IOS_$INQ_MGR_FLAGS (stream-id, status) 

RETURN VALUE 

mgr_ flags 

A set (bit mask) indicating the attributes of the specified object's manager, in 

IOS _$MGR_ FLAG _ SET format. This is a 4-byte integer. Any combination of the 

following set of predefined values, in IOS_$MGR_FLAG_T format, can be returned. If 

the set contains the value, the manager has the attribute and can perform the following 

operations: 



IOS _$MF_ CREATE 
IOS_$MF_CREATE_BAK 

IOS_$MF_IMEX 

IOS_$MF_FORK 

IOS _$MF_FORCE_ WRITE 

IOS_$MF_WRITE 
IOS_$MF_SEEK_ABS 

IOS_$MF_SEEK_SHORT 

IOS _ $MF _ SEEK_FULL 

IOS _ $MF _ SEEK_BYTE 

IOS _ $MF _ SEEK_REC 

IOS_$MF_SEEK_BOF 

IOS $MF REC TYPE 



Manager permits type to create objects. 

Manager permits type to create backup (.bak) 
objects. 

Manager permits type to export streams to 
new processes. 

Manager permits type to pass streams to 
forked processes. 

Manager permits type to force- write object 
contents to stable storage (for most types, this 
is the disk). 

Manager permits objects to be written to. 

Manager permits objects to perform absolute 
seeks. 

Manager permits objects to perform seeks 
using short (4-byte) seek keys. 

Manager permits objects to perform seeks 
using full (8-byte) seek keys. 

Manager permits objects to perform seeks to 
byte positions. 

Manager permits objects to perform seeks to 
record positions. 

Manager permits objects to perform seeks to 
the beginning of the object. 

Manager supports different record type 
formats. 
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IOS_$MF_ TRUNCATE Manager permits objects to be truncated. 

IOS_$MF_ UNREGULATED Manager permits objects to have unregulated 

(shared) concurrency mode. 

IOS_$MF_ SPARSE Manager permits objects to be written as 

sparse objects. 

IOS_$MF_READ_ INTEND _ WRITE Manager permits objects to have 

read-intend-write access. 



INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS _$INQ_MGR_ FLAGS to determine what operations an object's type manager 
can perform. 

Depending on the nature of the object, a type manager permits some of the operations 
identified by "mgr-flags." A manager usually will not support operations that are 
irrelevant for the object type. For example, if you called IOS_$INQ_MGR_FLAGS 
specifying a stream open on an SIO line, the set returned would not include any 
IOS _$MF_ SEEK attributes, since serial lines do not support seeking. 

Note that even if an object's manager permits an operation, the object itself can prevent the 
operation because the object's object and connection attributes must permit the operation 
as well. For example, a manager's attribute set might contain the attribute that permits 
writing to a file (IOS _$MF_ WRITE), but a specific object's connection attribute set 
might not include the IOS _$CF_ WRITE attribute, which permits writing on the 
connection. In this case, you cannot write to that particular object. However, you could 
possibly write to another object of the same type if the object's IOS _$CF_ WRITE 
attribute is set for its stream connection. 

To change object or connection attributes, use the IOS_$SET_OBJ_FLAGS and 
IOS _$SET_ CONN _ FLAGS calls, respectively. Which attributes you can change 
depends on the object type. Note that you cannot change manager attributes because the 
type manager determines them. For details on writing a type manager, see the Extending 
the DOMAIN Streams Facility manual. 
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IOS _ $INQ _ OB J_FLAGS 

Returns the attribute set associated with an object. 

FORMAT 

obj -flags = IOS_$INQ_OBJ_FLAGS (stream-id. status) 



RETURN VALUE 

obj- flags 

A set (bit mask) indicating the attributes of the specified object, in 
IOS_$OBJ_FLAG_SET format. This is a 4-byte integer. Any combination of the 
following set of predefined values, in IOS_$OBJ_FLAG_T format, can be returned. If 
the set contains the value, the object has the attribute and can perform the following 
operations: 



IOS_$OF_DELETE_ON_CLOSE 

IOS_$OF_SPARSE_OK 
IOS _$OF_ ASCII 
IOS_$OF_FTNCC 

IOS $OF COND 



Object will be deleted when all its associated 
streams close. 

Object can be written as a sparse object. 

Object contains ASCII data. 

Object uses FORTRAN carriage control 
characters. 

Get or put calls to the object will be 
performed conditionally, as if the 
IOS_$COND_OPT was specified on a get or 
put call. 



INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 
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OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use this call to determine which object attributes are in effect for the object on the specified 
stream. 

To change object or connection attributes, use the IOS_$SET_OBJ_FLAGS, and 
IOS _$SET_ CONN _ FLAGS calls respectively. The attributes that you can change 
depends on the object type. 
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IOS_$INQ_PATH_NAME 

Returns the pathname of the object open on a specified stream. 

FORMAT 

IOS_$INQ_PATH_NAME (stream-id, name-type, pathname, namelength, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

name-type 

Format of the returned pathname, in IOS_$NAME_TYPE_T format. Specify one of the 
following predefined values: 

IOS_$ROOT_NAME 

Return the absolute pathname, relative to the network root directory 
(//). For example, "//node/sid/file." 

IOS _ $WDIR _ NAME 

Return just the leaf name if the object's pathname is a name in the 
current working directory. Otherwise, return the absolute pathname. 

IOS_$NDIR_NAME 

Return just the leaf name if the object's pathname is a name in the 
current naming directory. Otherwise, return the absolute pathname. 

IOS _$NODE_ NAME 

Return a name relative to the node's entry directory (/) if the object's 
pathname is a name in the boot volume. Otherwise, return the absolute 
pathname. For example, "/sid/file." 

IOS_$NODE_DATA_FLAG 

Return just the leaf name if the object's pathname is a name in the 
'node _ data directory. Otherwise, return the absolute pathname. 

IOS _$LEAF_ NAME 

Return just the leaf name regardless of the object's pathname. For 
example, if the object's pathname is "/a/b/c," it returns "c." 

IOS_$RESID_NAME 

Return the residual part of a pathname if the stream is open using 
extended naming. (Extended naming allows you to add additional text to 
the end of a pathname.) 

OUTPUT PARAMETERS 

pathname 

Name of the object associated with the stream ID, in NAME_$PNAME_T format. This 
is an array of up to 256 characters. 
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namelength 

Length of the pathname. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use this call to determine the pathname of an object associated with the specified stream 
ID. Generally, use this call in cases where a program has been passed a stream ID and needs 
the associated pathname. 
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IOS_$INQ_REC_POS 

Returns the record position of the stream marker. 

FORMAT 

record_position = IOS_$INQ_REC_POS (stream-id, position-option, status) 

RETURN VALUE 

record-position 

Record position of the stream marker. This is a 4-byte integer. Note that record positions 
are zero-based; consequently, the record position of the beginning of the object is 0. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

position- option 

Value specifying the record position to return, in IOS_$POS_OPT_T format. This is a 
2-byte integer. Specify one of the following predefined values: 

IOS_$CURRENT Return the record position of the current stream marker. 

IOS_$EOF Return the record position of the end of the object (EOF) 

stream marker. This is the number of records in the object. 

IOS_$BOF Return the record position of the beginning of the object (BOF) 

stream marker. This value is always 0. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

To obtain the offset of the stream marker for record-oriented objects, use 
IOS_$INQ_REC_POS. (UseIOS_$INQ_BYTE_POS if your object is not 
record-oriented.) 

To get the offset of the stream marker at the beginning or end of the object, specify 
IOS_$BOF or IOS_$EOF, in the "position-option" parameter. Specify 
IOS_$CURRENT to get the offset of the stream marker from the beginning of the object. 
Once you have the returned offset, you can move the stream marker to desired location by 
calling IOS_$SEEK. 

This call allows you to perform a nonkeyed seek by specifying an absolute byte position, or 
by getting an offset from an absolute position, and moving the stream marker to it. 
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Whether you perform a nonkeyed or keyed seek depends on how the object's data is 
represented. For example, programs that need to perform "arithmetic" on the data (such 
as comparing two positions) will use nonkeyed seek operations. Programs that require only 
the ability to move from one position to another in an object will use keyed seek operations. 
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IOS_$INQ_REC_REMAINDER 

IOS_$INQ_REC_REMAINDER 

Returns the number of bytes remaining in the current record. 

FORMAT 

bytes = IOS_$INQ_REC_REMAINDER (stream-id, status) 

RETURN VALUE 

bytes 

Number of bytes remaining in the current record. This is a 4-byte integer. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the file is open, in IOS_$ID_T format. This is a 2-byte 
integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. • This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS_$INQ_REC_REMAINDER with the IOS_$GET or IOS_$LOCATE calls. If 
IOS_$GET or IOS_$LOCATE fills the specified buffer, but has not yet finished reading a 
record, it returns the IOS _$BUFFER_ TOO _ SMALL error status code. At this point, 
use IOS _$INQ_REC_ REMAINDER to determine the number of bytes in the record that 
remain to be read. If the entire record has been read, the value of "bytes" is undefined. 
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IOS_$INQ_REC_TYPE 

Returns the record type of an object. 

FORMAT 

record- type = IOS_$INQ_REC_TYPE (stream-id, status) 

RETURN VALUE 

record-type 

Type of record format used in the specified object, in IOS_$RTYPE_T format. This is a 
2-byte integer. Returns one of the following predefined values: 

IOS_$Vl Variable-length records with count fields. 

IOS_$Fl Fixed-length records without count fields. 

IOS_$F2 Fixed-length records with count fields. 

IOS_$EXPLICIT_F2 Fixed-length records that IOS_$PUT cannot implicitly change 

to variable-length records. 

IOS_$UNDEF No record structure. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS _$INQ_REC_ TYPE to determine how records within an object are formatted. 
You can change the record type of a record-oriented object by calling 
IOS_$SET_REC_TYPE. 

By default, a record-oriented object has fixed-length records (IOS_$F2). They remain 
fixed-length records until IOS_$PUT writes records of different lengths. At this point, 
IOS_$PUT implicitly changes the objects to variable-length type (IOS_$Vl). In some 
cases, you might want to explicitly set the record type to IOS_$EXPLICIT_F2 so that an 
attempt to write a variable-length record results in an error. To do so, use the 
corresponding call, IOS_$SET_REC_TYPE. 
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IOS_$INQ_SHORT_KEY 

IOS_$INQ_SHORT_KEY 
Returns a short seek key. 

FORMAT 

short-key = IOS_$INQ_SHORT_SEEK (stream-id, position-option, status) 

RETURN VALUE 

short- key 

Short seek key to be used in subsequent seeks. This is a 4-byte integer. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

position-option 

Value specifying the position to return, in IOS_$POS_OPT_T format. This is a 2-byte 
integer. Specify only one of the following predefined values: 

IOS_$CURRENT Return the short seek key of the current marker. 

IOS_$EOF Return the short seek key of the end of the object (EOF) 

marker. 

IOS_$BOF Return the short seek key of the beginning of the object (BOF) 

marker. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

IOS _$INQ_ SHORT _ KEY returns a seek key based on the position option you specify — 
the current stream marker position, beginning or end of the object. 

You use seek keys to perform random access of data. Typically, you use this call to inquire 
about a seek key before writing some data, and then store the seek key. To access the data 
at a later time, position the stream marker by calling the IOS _$ SEEK _ SHORT _ KEY 
call with the stored seek key, and get the data with an IOS get operation (IOS_$GET or 
IOS_$LO0ATE). 

Use seek keys merely as an index ~ do not count on the contents of the keys. The contents 
of seek keys remain private to the IOS manager, which guarantees only that the seek key 
returns to the position it describes. 
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Some object types support seek key positioning, but not record or byte positioning. Use 
seek keys for repositioning if your application does not need the "arithmetic" properties of 
record- or byte-positioning (that is, the ability to compute positions given positions). 

The DOMAIN system offers both short (4-byte) and full (8-byte) seek keys. Because short 
seek keys require half the storage space of full seek keys, you might want to use short seek 
keys if your application program stores a large number of seek keys. However, short seek 
keys are limiting in that you can only indicate record boundary positions, while full seek 
keys allow you to indicate any position. 
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IOS_$INQ_TYPE_UID 

IOS_$INQ_TYPE_UID 

Returns the type UK) of an object. 

FORMAT 

IOS_$INQ_TYFE_UID (stream-id, type-uid. status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

type-uid 

Type UK) of the object, in UK)_$T format. This data type is 8 bytes long. See the IOS 
Data Types section for more information. 

DOMAIN currently supports a set of predefined standard object types which include the 
following types. (Note that users can also define their own type UIDs by writing a type 
manager. See the Using the Open System Toolkit to Extend the Streams Facility manual 
for details. ) 

Type UID Object 

UASC_$UK> UASO object 

RECORDS _$UK) Record-oriented object 

HDR_UNDEF_$UK> Nonrecord-oriented object 

OBJECT _FKE_$UK) Object module object (compiler or binder output) 

SIO_$UK) Serial line descriptor object 

MT_$UK) Magnetic tape descriptor object 

PAD _ $UK) Saved display manager transcript pad 

INPUT _ PAD _$UK> Display manager input pad 

MBX_$UK) Mailbox object 

DIRECTORY_$UID Directory 

NULLDEV_$UK> Null device 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 
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USAGE 



Use this call to determine the object's current type UID given its stream ID. You can use 
the type UID returned by this call as a parameter in the IOS_$CREATE call to create 
another object of the same type. 
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IOS $LOCATE 

r \ 

\^_y Reads data from a stream, and returns a pointer to the data. 

FORMAT 

ret-length = IOS_$LOCATE (stream-id, get-options, data-ptr, data-size. 

status) 

RETURN VALUE 

ret-length 

Amount of data read, in bytes. This is a 4-byte integer. 

"Ret-length" equals the amount of data read; "ret-length" equals if IOS_$LOCATE does 
not return any data. 

/"""""N If the length of the data read exceeds the amount specified in "data-size," IOS_$LOCATE 

\___y ( performs the following: 

• Reads enough data to fill the requested size 

• Sets "ret-length" equal to "data-size" 

• Positions the stream marker to the first unread byte 

• Returns the IOS _$BUFFER_ TOO _ SMALL status code to indicate that this 
condition has occurred 

You can inquire about how many bytes remain to be read in the current record by calling 
IOS _ $INQ _REC _REMAINDER. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

get- options 

Options that control how IOS_$LOCATE performs the get operation, in 

IOS _ $PUT_ GET _ OPTS _T format. This is a 2-byte integer. Specify a combination of 

the following set of predefined values: 

IOS_$COND_OPT Reads data, if available. (For example, data 

on an SIO line is not always available 
immediately.) If the data is not available, 
IOS_$GET returns the 
IOS _ $GET _ CONDITIONAL _FAILED 
status code and sets the return value of 
"ret-length" to 0. 

IOS_$PREVIEW_OPT Reads data but does not update the stream 

marker. 
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IOS_$NO_REC_BNDRY_OPT Ignores record boundaries while reading data. 

For example, it ignores NEWLINE characters 
in a UASC object, which guarantees that the 
call fills the specified buffer. Some type 
managers might not support this call. 

IOS _ $PARTIAL _ RECORD _ OPT Not meaningful for this call. 

data-size 

Maximum amount of data to be read, in bytes. This is a 4-byte integer. 

OUTPUT PARAMETERS 

data-ptr 

A pointer to the located data, in UNIV_PTR format. This is a 4-byte integer. Note that 
this pointer remains valid only until the program invokes the next IOS call. 

If IOS_$LOCATE is unable to return a pointer to the location of the data, it copies the 
data into a system buffer and then returns the address of the buffer in "data-ptr." (See the 
USAGE Section below for more details.) 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

You can use either IOS_$LOCATE or IOS_$GET to read data from system objects. 
IOS _ $LOCATE returns a pointer to the data, while IOS _ $GET copies the data into a 
buffer. 

In most cases, use the IOS_$LOCATE call to read data because it is faster 
(IOS_$LOCATE does not perform a copy). 

You will want to use IOS _ $GET when you need to read more data than can be obtained in 
one call, because the pointer remains valid for only one call. For example, when you need 
to read and rearrange a number of lines from an object. 

Normally, IOS_$LOCATE locates data and returns a pointer to the data. However, not 
all managers support the internal buffering necessary for IOS_$LOCATE to work this 
way. In these cases, IOS_$LOCATE will not be able to return a pointer to the data. 

Instead, IOS_$LOCATE actually creates a buffer and then calls IOS_$GET to perform 
the get call. In this case, IOS_$LOCATE is no more efficient than IOS_$GET. The size 
of the buffer that IOS_$LOCATE creates is either the length you specify in "data-size," or 
1024 bytes, whichever is the smaller. 

Use IOS _$SET_ LOCATE _ BUFFER _ SIZE to specify a buffer larger than 1024 bytes, if 
necessary. In this case, IOS_$LOCATE is no more efficient than IOS_$GET. 

See the IOS_$SET_LOCATE_BUFFER_SIZE call description for more information. 
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IOS_$OPEN 

Opens a stream to an existing object. 

FORMAT 

stream-id = IOS_$OPEN (pathname, namelength, open-options, status) 

RETURN VALUE 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

INPUT PARAMETERS 

pathname 

Name of the object to be opened, in NAME_$PNAME_T format. This is an array of up 
to 256 characters. 

namelength 

Length of the pathname. This is a 2-byte integer. 

open- options 

Options available at open time, in IOS_$OPEN_ OPTIONS _T format. This is a 2-byte 
integer. Specify a combination of the following set of predefined values: 

IOS _ $NO _ OPEN_DELAY_ OPT Return immediately, instead of waiting for the 

open call to complete. 

IOS_$WRITE_OPT Permit writing data to a new object. If a 

program tries to write on a stream for which 
you have not specified this option, it returns 
an error status. 

IOS_$UNREGULATED_OPT Permit shared (unregulated) concurrency 

mode. 

IOS_$POSITION_TO_EOF_OPT Position the stream marker at the end of the 

object (EOF). Use this to append data to an 
existing object. 

IOS_$INQUIRE_ONLY_OPT Open the object for attribute inquiries only; 

do not permit reading or writing of data. 

IOS _$READ_ INTEND _ WRITE _ OPT Open the object for read access with the 

intent to eventually change the object's access 
to write access. This allows other processes to 
read the object; but they cannot have write or 
read-intend-write access. 
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OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

This routine opens a stream to the named object. It returns the stream ID to be used in 
subsequent stream activity with the object. An error occurs if the object does not exist. If 
the object already exists, IOS_$OPEN does not change its attributes. 

IOS_$OPEN does not return information about the object's attributes. To get information 
about an object, use the calls with the prefix IOS_$INQ. To change an object's attributes, 
use the calls with the prefix IOS_$SET. 
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IOS_$PUT 

Writes data into an object. 

FORMAT 

IOS_$PUT (stream-id, put-options, buffer, buffer-size, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

put- options 

Options that control how IOS_$PUT performs the put operation, in 

IOS _ $PUT_ GET _ OPTS __T format. This is a 2-byte integer. Specify any combination 

of the following set of predefined values: 

IOS_$COND_OPT Write a record only if it can be done without 

blocking. If the call would block, it returns 
the IOS _$PUT_ CONDITIONAL _FAILED 
error status. 

IOS_$PREVIEW_OPT Write data but do not update the stream 

marker. 

IOS _$PARTIAL_ RECORD _ OPT Write a portion of a record but do not 

terminate it. IOS_$PUT terminates the 
record when you call IOS_$PUT without 
specifying this option. If you do not specify 
this option, IOS_$PUT writes a full record. 
You can use this option with record-oriented 
objects only. IOS_$PUT ignores this option 
if you specify it with any other type of 
objects. 

IOS _ $NO _REC _BNDRY_ OPT Not meaningful for this call. 

buffer 

Buffer to contain the data. This is a character array. 

buffer-size 

Size of the buffer containing the data, in bytes. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 
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USAGE 



IOS_$PUT writes data into an object. Use "put-options," which is in the 

IOS _ $PUT_ GET _ OPTS _T format, to write the data to the object in different ways. 

If the object is record-oriented, you can write data to it record by record. This is the 
default action (for record-oriented objects) when you specify the default ([]) value in 
"put-option." 

To write a single record with more than one put operation (for example, to write one field 
at a time), use the IOS_$PARTIAL_RECORD_OPT option. If you specify this option, 
IOS_$PUT writes the data, but does not terminate the record. IOS_$PUT terminates the 
record when you call it without specifying this option. 

To write to objects which might not always be immediately available (for example, an MBX 
channel), you perform conditional put operations with the IOS_$COND_OPT option. 
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IOS_$REPLICATE 

Creates a copy of a specified stream ID. 

FORMAT 

return_stream_id = IOS_$REPLICATE (stream_id_to_replicate, copy_stream_id / 

status) 

RETURN VALUE 

return _ stream _ id 

Number of the new stream created, in IOS_$ID_T format. This is a 2-byte integer. 

INPUT PARAMETERS 

stream_id_to_replicate 

Number of the stream to replicate, in IOS_$ID_T format. This is a 2-byte integer. This 
stream number remains a valid connection to the object after IOS _ $REPLICATE 
completes successfully. 

copy _ stream _ id 

Number of the stream to use as the copy for " stream _ id _ to _ replicate," in IOS_$ID_T 
format. This is a 2-byte integer. 

If " copy _ stream _ id" is free, IOS_$REPLICATE returns that number in 
" return _ stream _ id." If "copy-stream-id" is in use, IOS _ $REPLICATE begins searching 
from that number downward (lower numbers) until it finds a free stream number, and 
returns that number in " return _ stream _ id." 

If the actual number of the copy stream is insignificant, specify the predefined constant 
IOS_$MAX. This value causes IOS_$REPLICATE to begin searching at the highest 
possible stream number and return the first free stream number it finds. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS _ $REPLICATE to create a copy of an existing stream ID. The new stream ID 
refers to the same connection as the existing stream ID. Note that you must close both 
streams with IOS_$CLOSE before the stream connection actually closes. 

IOS_$REPLICATE is identical to IOS_$DUP except that IOS _ $REPICATE looks for a 
free stream in descending order from the specified stream ID, while IOS_$DUP looks in 
ascending order. Note that you use IOS_$DUP or IOS _ $REPLICATE to copy existing 
stream ID's, both the existing and new stream ID's remain valid connections. However, you 
use IOS_$SWITCH to replace stream IDs; you "switch" the connection from the existing 
stream ID to the new stream ID. 
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You can use IOS _ $REPLICATE to keep a stream connection open when passing it to a 
subroutine. Use IOS_$REPLICATE to create a copy of the stream ID before passing it. 
This way, the subroutine cannot close the connection to the object because all copies of the 
stream connection must be closed before the connection itself gets closed. 



IOS_$RELPLICATE is analagous to UNIX DUP. 
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IOS_$SEEK 

IOS_$SEEK 

Performs an absolute or relative seek using byte or record positioning. 

FORMAT 

IOS_$SEEK (stream-id, abs-rel, seek-type, offset, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

abs-rel 

Value specifying the base for the seek operation, in IOS_$ABS_REL_T format. This is 
a 2-byte integer. Specify one of the following predefined values: 

IOS _ $RELATIVE The seek is relative to the current position. 

IOS_$ABSOLUTE The seek is relative to the beginning of the object (BOF). 

seek-type 

The type of seek to be performed, in IOS _$SEEK_ TYPE _T format. This is a 2-byte 
integer. Specify one of the following predefined values: 

IOS _ $REC _ SEEK Record-oriented seek. 

IOS _$BYTE_ SEEK Byte-oriented seek. 

offset 

A signed integer offset value indicating the number of records or bytes from the seek base 
to position the stream marker. This is a 4-byte integer. 

If the integer is a positive number, IOS_$SEEK uses BOF as the seek base and searches 
forward. If the integer is a negative number, IOS_$SEEK uses EOF as the seek base and 
searches backward. Whether the offset indicates bytes or records depends on the type of 
seek you specified in "seek-type." 

You can get an offset number to use in an absolute seek with the calls 
IOS_$INQ_BYTE_POS and IOS_$INQ_REC_POS. 

Note that both byte and record positions are zero-based; consequently, the first byte or 
record number is 0. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 
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USAGE 

Use IOS_$SEEK to seek to an absolute or relative byte or record position within an object. 

You can use this call with the IOS_$INQ_BYTE_POS and IOS_$INQ_REC_POS 
calls to perform absolute position seeks. 
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IOS _ $SEEK_FULL _KEY 

Performs a seek using a full (8-byte) seek key. 

FORMAT 

IOS_$SEEK_FULL_KEY (stream-id, full-key. status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

full- key 

A full seek key, in IOS_$SEEK_KEY_T format. This data type is 8 bytes long. See the 
IOS Data Types section for more information. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Before performing a full key seek, you must first obtain a full seek key by using the 
IOS _ $INQ_ FULL _ KEY call. This call allows you to inquire about a seek key before 
writing some data, and then store the seek key. To access the data at a later time, position 
the stream marker by calling the IOS _$ SEEK _ FULL _ KEY call with the stored seek key, 
and then get the data with an IOS get call (IOS_$GET or IOS_$LOCATE). 
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IOS _ $SEEK_ SHORT_KEY 

Performs a seek using a short (4-byte) seek key. 

FORMAT 

IOS_$SEEK_SHORT_KEY (stream-id, short-key, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

short- key 

A short seek key. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Before performing a short key seek, you must first obtain a short seek key by using the 
IOS _$INQ_ SHORT _KEY call. This call allows you to inquire about a seek key before 
writing some data, and then store the seek key. To access the data at a later time, position 
the stream marker by calling IOS _$SEEK_ SHORT _ KEY with the stored seek key, and 
then get the data with an IOS get call (IOS_$GET or IOS_$LOCATE). 
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IOS_$SEEK_TO_BOF 

Positions the stream marker to the beginning of an object. 

FORMAT 

IOS_$SEEK_TO_BOF (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS_$SEEK_TO_BOF to position the stream marker to the beginning of an object 
(BOF). Use this call when performing a nonkeyed seek on an object. 
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IOS_$SEEK_TO_EOF 

Positions the stream marker to the end of an object. 

FORMAT 

IOS_$SEEK_TO_EOF (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS_$SEEK_TO_EOF to position the stream marker to the end of an object (EOF). 
Use this call when performing a nonkeyed seek on an object. 
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IOS_$SET_CONN_FLAG 

Changes the set of connection attributes associated with a stream connection. 

FORMAT 

IOS_$SET_CONN_FLAG (stream-id, conn-flag, on-off, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ED__T format. This is a 
2-byte integer. 

conn-flag 

Flag indicating which attribute of the specified connection you want to change, in 

IOS _$CONN_ FLAG _T format. This is a 2-byte integer. Specify one of the following 

predefined values: 

IOS_$CF_TTY Connection behaves like a terminal. 

IOS_$CF_IPC Connection behaves like an interprocess 

communication (IPC) channel. 

IOS _ $CF _ VT Connection behaves like a DOMAIN Display 

Manager pad. 

IOS _$CF_ WRITE Connection can be written to. 

IOS _$CF_ APPEND Connection's stream marker will be positioned 

at the end of the object (EOF) before each put 
call. 

IOS_$CF_UNREGULATED Connection is open for unregulated (shared) 

concurrency mode. 

IOS_$CF_READ_INTEND_WRITE Connection is open for read access, and can be 

changed to write access. Other connections 
can have read access, but not write or 
read-intend- write access. 

on-off 

Boolean value indicating whether the specified attribute should be included in the set (on), 
or removed from the set (off). 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 
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USAGE 



Use IOS _$SET_ CONN _ FLAG to change the attributes of a connection. Note that 
objects do not support all connection attributes. To determine the connection's current set 
of attributes, use IOS_$INQ_CONN_FLAGS before using this call. 

To change the set of attributes, you must call IOS _$SET_ CONN _FLAG for each 
connection attribute you want to change. To add an attribute to the set, call 
IOS_$SET_CONN_FLAG, specifying the desired attribute, and set the "on-off" 
parameter to TRUE. To remove an attribute from the set, use this call, specifying the 
attribute to remove, and set the "on-off" parameter to FALSE. 

Before an object can permit the operation indicated by an attribute, the object's manager 
and connection attributes must permit the operation as well. For example, a manager's 
attribute set might contain the attribute that permits writing to an object 
(IOS _$MF_ WRITE), but a specific object's connection attribute set might not include the 
IOS _$CF_ WRITE attribute, which permits writing to the object. In this case, you 
cannot write to that particular object. 
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IOS_$SET_DIR 

IOS_$SET_DIR 

Changes the current working or naming directory. 

FORMAT 

IOS_$SET_DIR (pathname, namelength, dir_type, status) 

INPUT PARAMETERS 

pathname 

Name of the directory to set, in NAME_$PNAME_T format. This is an array of up to 
256 characters. 

namelength 

Length of "pathname." This is a 2-byte integer. 

dir_type 

Option specifying which type of directory to set, in IOS_$DIR_TYPE_T format. 
Specify one of the predefined values: 

IOS_$WDIR Name of the current working directory. 
IOS_$NDIR Name of the current naming directory. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use this call to change the current working or naming directory. You can use 
IOS_$GET_DIR to get the name of the current working or naming directory. 
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IOS_$SET_LOCATE_BUFFER_SIZE 

Sets the size of the buffer that IOS_$LOCATE allocates. 

FORMAT 

IOS_$SET_LOCATE_BUFFER_SIZE (stream-id. buffer-size, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

buffer- size 

Size of the buffer you want to allocate. This is a 2-byte integer. 

OUTPUT PARAMETERS ^_ 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Normally, IOS_$LOCATE locates data and returns a pointer to the data. However, not / 

all managers support the internal buffering necessary for IOS_$LOCATE to work this v__ 

way. In these cases, IOS_$LOCATE will not be able to return a pointer to the data. 

Instead, IOS_$LOCATE actually creates a buffer and then calls IOS_$GET to perform 
the get call. In this case, IOS_$LOCATE is no more efficient than IOS_$GET. The size 
of the buffer that IOS_$LOCATE creates is either the length you specify in "data-size," or 
1024 bytes, whichever is the smaller. 

Use IOS _$SET_ LOCATE _ BUFFER _ SIZE to specify a buffer larger than 1024 bytes, if (~ 

necessary. V,_. 

For example, if you are using IOS_$LOCATE with a data-size parameter of 2000 bytes, 
and the manager of the object from which you are reading does not support internal 
buffering, the IOS_$LOCATE call, by default, will copy as much of the requested data as 
it can into a 1024-byte-long buffer and return a pointer to that buffer. 

However, if you precede the IOS_$LOCATE call with a call to 

IOS _$SET_ LOCATE _ BUFFER _ SIZE, specifying a buffer-size of 2000, the 

IOS_$LOCATE call will use a 2000-byte-long buffer and will be able to copy all the 

requested data into the buffer. This new buffer size will be valid as long as the stream 

exists. 
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IOS_$SET_OBJ_FLAG 

IOS_$SET_OBJ_FLAG 

Changes the set of object attributes associated with an object. 

FORMAT 

IOS_$SET_OBJ_FLAG (stream-id, obj-flag. on-off. status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

obj-flag 

Flag indicating which attribute of the specified object you want to change, in 
IOS_$OBJ_FLAG_T format. This is a 2-byte integer. Specify one of the following 
predefined values: 

IOS_$OF_DELETE_ON_CLOSE Object will be deleted when all its associated 

streams close. 

IOS _$ OF _ SPARSE _ OK Object can be written as a sparse object. 

IOS_$OF_ ASCII Object contains ASCII data. 

IOS_$OF_FTNCC Object uses FORTRAN carriage control 

characters. 

IOS_$OF_COND Get or put calls to the object will be 

performed conditionally, as if the 
IOS_$COND_OPT was specified on a get or 
put call. 

on-off 

Boolean value indicating whether the specified attribute should be included in the set (on), 
or removed from the set (off). 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 
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USAGE 



Use IOS_$SET_OBJ_FLAGS to change the attributes of an object. Note that objects do 
not support all object attributes. To determine the object's current attribute set, use the 
IOS_$INQ_OBJ_FLAGS call. 

To change an object's attribute set, you must call IOS_$SET_OBJ_FLAG once for each 
object attribute you want to change. To add an attribute to the set, call 
IOS _$SET_ OBJ _ FLAG, specifying the desired attribute, and set the "on-off" parameter 
to TRUE. To remove an attribute from the set, use this call, specifying the attribute to 
remove, and set the "on-off" parameter to FALSE. 

Before an object can permit the operation indicated by an attribute, the object's manager 
and object attributes must permit the operation as well. For example, a manager's 
attribute set might contain the attribute that allows the object to perform put and get calls 
conditionally (IOS_$MF_COND), but a specific object's object attribute set might not 
include the IOS_$OF_COND attribute. In this case, you cannot make conditional put or 
get calls to that particular object. 
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IOS_$SET_REO_TYPE 

Sets the record type format and (optionally) record length of a file. 

FORMAT 

IOS_$SET_REC_TYPE (stream-id. record- type, record-length, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in IOS_$ID_T format. This is a 
2-byte integer. 

record-type 

Type of record format to change for the specified object, in IOS_$RTYPE_T format. 
This is a 2-byte integer. Specify one of the following predefined values: 

IOS_$Vl Variable-length records with count fields. 

IOS_$Fl Fixed-length records without count fields. 

IOS_$F2 Fixed-length records with count fields. However, IOS_$PUT 

can change the IOS_$F2 type to IOS_$Vl implicitly. (See 
Usage section below.) 

IOS_$EXPLICIT_F2 Fixed-length records that IOS_$PUT cannot implicitly change 

to variable-length records. (IOS_$PUT can change the 
IOS_$F2 to IOS_$Vl implicitly. See Usage section below.) 

IOS_$UNDEF No record structure. 

record- length 

Length to set for the fixed-length records of the object. This is a 4-byte integer. Specify 
this value only if the object is empty. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

By default, a record-oriented object has fixed-length records (IOS_$F2). They remain 
fixed-length records until IOS_$PUT writes records of different lengths. At this point, 
IOS_$PUT implicitly changes the objects to variable-length type (IOS_$Vl). In some 
cases, you might want to explicitly set the record type to IOS_$EXPLICIT_F2 so that an 
attempt to write a variable-length record results in an error. To do so, use this call. 
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IOS_$SWITCH 

Switches a stream from one stream ID to another stream ID. 

FORMAT 

ret-stream-id = IOS_$SWITCH (stream-id-to-switch, new-stream-id, status) 

RETURN VALUE 

ret- stream- id 

Number of the new stream ID that replaces the existing stream ID, in IOS_$ID_T format. 
This is a 2-byte integer. 

INPUT PARAMETERS 

stream-id-to-switch 

Number of the stream to switch, in IOS_$ID_T format. This is a 2-byte integer. 

This stream number becomes invalid after the IOS_$SWITCH call completes sucessfully. 

new- stream- id 

Number of the stream to use as the new stream ID, in IOS_$ID_T format. This is a 
2-byte integer. 

If "new-stream-id" is free, IOS_$SWITCH returns this value in "ret-stream-id." If ,^~^ 

"new-stream-id" is in use, IOS_$S WITCH begins searching from that value downward I , 

(lower numbers) until it finds a free stream number and returns that number in 
"ret-stream-id." 

If the actual number of the replacement stream is insignificant, specify the predefined 
constant IOS_$MAX. This value causes IOS_$SWITCH to begins searching at highest 
possible stream number and return the first free number it finds. 

OUTPUT PARAMETERS ^ 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

Use IOS_$SWITCH to switch one stream ID for another. The new stream ID refers to the 
same connection as the old stream ID, making the old stream ID invalid. 

Note that you use IOS_$SWTICH to replace stream IDs; you "switch" the connection 
from the existing stream ID to the new stream ID. However, you use IOS_$DUP or 
IOS _ $REPLICATE to copy existing stream IDs, both the existing and new stream IDs 
remain valid connections. 
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IOS_$TRUNCATE 

Deletes the contents of an object following the current stream marker. 

FORMAT 

IOS_$TRUNCATE (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in IOS_$ID_T format. This is a 2-byte 
integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IOS 
Data Types section for more information. 

USAGE 

IOS _ $TRUNCATE decreases the value of the object's length attribute to match the 
stream marker. (Writing data to a stream that lengthens the object implicitly increases this 
attribute's value.) This call sets the stream marker to the end of the object (EOF), 
effectively deleting any data in the object past the stream marker. If the stream position is 
already at EOF, IOS _ $TRUNCATE has no effect. 

Truncating an object does not close the stream. 
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ERRORS 

IOS _ $ALREADY_EXISTS 

Object already exists; detected by IOS_$CREATE with IOS_$NO_PREXIST 
option. 

IOS _ $BAD _ CHAR_SEEK 

Attempted character seek before start of current (variable-length) record. 

IOS_$BAD_COUNT_FIELD_IN_FILE 

Count field for current record is wrong. 

IOS_$BAD_FILE_HDR 

Wrong stream file header. 

IOS _ $BAD _LOCATION 

Bad location parameter on IOS_$CREATE call.. 

IOS_$BAD_OPEN_XP 

OPEN_XP must reference a stream that is already open in this process. 

IOS _ $BAD _ SHARED _ CURSOR _ REFCNT 

Reference count on a shared object cursor went below zero. 

IOS_$BOF_ERR 

Attempted seek beyond beginning of object (BOF). 

IOS_$BUFFER_TOO_BIG 

Buffer size too large on IOS_$GET or IOS_$LOCATE call. 

IOS _ $BUFFER _ TOO _ SMALL 

Buffer too small on IOS_$GET or IOS_$LOCATE call, warning. 

IOS _ $CANT _ CHANGE _ TYPE 

Cannot change the type as requested, detected by IOS_$CREATE. 

IOS _ $CANT_DELETE_ OLD _NAME 

Added new name, but cannot delete old name. ^_ 

f 

IOS _$CANT_ INITIALIZE V 

Cannot initialize an object of this type. 

IOS_$CANT_SET_ADVISORY_LOCK 

Advisory lock already set on this object. 

IOS _ $CONCURRENCY_ VIOLATION 

Requested access violates concurrency constraints, object is in use. 

IOS_$DEVICE_MUST_BE_LOCAL 

Cannot open stream to remote device. 

IOS_$DIR_NOT_FOUND 

Couldn't find directory in pathname on IOS_$CREATE. 

IOS_$END_OF_FILE 
End of file. 

IOS_$FILE_NOT_EMPTY 
Object not empty. 
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IOS _ $FLAG _ NOT._ SUPPORTED 

Flag not supported for this object type. 

IOS_$FROM_ID_NOT_OPEN 

Stream ID to switch not open on IOS_$SWITCH. 

IOS _ $FULL _ REC _ UNAVAIL 

IOS_$GET or IOS_$LOOATE requested a full record, but only part of the record 
was available. The call returns the part that is available along with this warning that 
there is still more room in the buffer. 

IOS _ $GET _ CONDITIONAL _FAILED 

Cannot read any data because the stream is empty; detected by IOS_$COND_OPT 
option. 

IOS_$ID_OOR 

Stream ID is out-of-range or invalid. 

IOS _ $ILLEGAL _ NAME _REDEFINE 

Attempted name change would require object to be moved, detected by 
IOS _ $CHANGE _ PATH _ NAME. 

IOS _ $ILLEGAL _ OB J _ TYPE 

Cannot open a stream for this type of object. 

IOS _ $ILLEGAL _ OPERATION 

Operation illegal on named stream. 

IOS_$ILLEGAL_PAD_CREATE_TYPE 

Cannot perform this operation on a pad type. 

IOS_$ILLEGAL_PARAM_COMB 

Illegal parameter combination for this operation. 

IOS_$ILLEGAL_W_VAR_LGTH_RECS 

Operation illegal with variable-length records. 

IOS _ $INQ _ ONLY_ ERROR 
-—^ Can only open this operation for inquiries only. 

v~-/ IOS _ $INSUFFICIENT _ RIGHTS 

Insufficient rights for requested access to object. 

IOS _ $INSUFF _MEMORY 

Not enough address space. 

IOS _ $INTERNAL _ FATAL _ ERR 

Internal fatal error on table re-verify operation. 

IOS _ $INTERNAL _MM_ERR 

Internal fatal error in stream memory management (windowing). 

IOS _ $INVALID _DATA 

Cannot write this data to object. 

IOS_$NAME_NOT_FOUND 
Name not found. 

IOS_$NAME_REQD 

Must specify name on IOS_$OPEN. 
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IOS _ $NEED _MOVE _MODE 

IOS_$LOCATE operation refused, try IOS_$GET. 

IOS _ $NEVER _ CLOSED 

System (or process) crash prevented complete close of object. 

IOS _ $NO _ ADVISORY_LOCK_SET 
No advisory lock to unlock. 

IOS _ $NO _ AVAIL _ TARGET 

No available target stream to switch to on IOS _ $SWITCH. 

IOS _ $NO _MORE_ STREAMS 

No more available stream IDs. 

IOS_$NO_RIGHTS 

No rights to access object. 

IOS_$NO_TABLE_SPACE 
Internal error. 

IOS _$NOT_A_ DIRECTORY 

Name specified is not a directory detected by IOS_$GET_DIR or _$SET_DIR. 

IOS_$NOT_AT_REC_BNDRY 

Cannot perform operation with short key — must be at a record boundary. 

IOS _$NOT_ OPEN 

Operation attempted on unopened stream. 

IOS_$OBJ_DELETED 

Object has been deleted while open on this stream. 

IOS_$OBJECT_NOT_FOUND 

Object associated with this name not found even though name exists. 

IOS _ $OBJECT_READ _ ONLY 

Cannot open this object for writing. 

IOS_$OUT_OF_SHARED_CURSORS /" "\ 

Internal error. v , 

IOS_$PART_REC_WARN 

Partial record at EOF on IOS_$CLOSE - warning only. 

IOS_$PERM_FILE_NEEDS_NAME 

Only temporary objects can be unnamed, you must name a permanent object. 

IOS_$PUT_BAD_REC_LEN 

Attempted an IOS_$PUT on a record of the wrong length. 

IOS _ $PUT _ CONDITIONAL _FAILED 

Cannot write any data because the stream is full, detected by IOS_$COND__OPT 
option. 

IOS _ $READ _ ONLY_ ERR 

Attempted to write to read-only stream. 

IOS_$RESOURCE_L0CK_ERR ( ^ 

Unable to lock resources required to process request. ~" 
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IOS_$SIO_NOT_LOCAL 

No stream found in conditional put, or cannot open a remote SIO line. 

IOS _ $SOMETHING_FAILED 

Cannot locate attribute set inquiring about manager, connection or object attributes; 
or cannot change the connection or object attribute requested. 

IOS _ $TARGET_INUSE 

Target ID already in use on IOS_$SWITCH, no available stream IDs. 

IOS_$XP_BUF_TOO_SMALL 

Buffer supplied to IOS_$EXPORT too small. 
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IOS DIR 



The IOS_DIR (I/O Switch Directory) programming calls provide less expensive streams access to 
file system objects. This section describes their data types, call syntax, and error codes. Refer to 
the Introduction at the beginning of this manual for a description of data-type diagrams and call 
syntax format. 

Note that programs use the IOS_DIR calls to request the services of a type manager's IOS_DIR 
trait; a type manager does not usually use the IOS _ DIR calls. Also, when you use the IOS _ DIR 
calls, you must include the /sys/ins/ios.ins.lan insert file before you include the 
/sys/ins/ios_dir.ins.lan insert file. 
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IOS DIR DATA TYPES 



CONSTANTS 



IOS_DIR_$ENTTYPE_FILE 1 

IOS_DIR_$ENTTYPE_LINK 3 

IOS DIR $DIR ENTRY SIZE 44 



A directory entry for a file. 

A directory entry for a link. 

Size of a directory entry (ios _ dir_$dir_ entry _t). 



DATA TYPES 



IOS $ID T 



IOS $OPEN OPTIONS T 



NAME SPNAME T 



IOS DIR $ENTRY T 



A 2-byte integer, ranging in value from to 
IOS_$MAX. The stream ID. 

A 2-byte integer. Specifies options for opening a 
stream connection. Any combination of the 
following predefined values: 

IOS_$INQUIRE_ONLY_OPT 

Open the object for attribute inquires only; do 

not permit reading or writing of data. 

IOS_$NO_OPEN_DELAY_OPT 

Return immediately, instead of waiting for the 

open call to complete. 

IOS_$POSITION_TO_EOF_OPT 

Position the stream marker to the end of the 

object (EOF). 

IOS_$READ _INTEND _WRITE_OPT 
Open the object for read access with the 
intent to eventually change to write access. 
This allows other processes to read the object, 
but they cannot have write or 
read-intend-write access. 

IOS _ $UNREGULATED _ OPT 

Permit shared (unregulated) concurrency 

mode. 

IOS_$WRITE_OPT 

Permit writing to the object. 

An array of up to name _$pnamlen_ max (256) 
characters. 

The format of a record in an IOS _ DIR object (that 
is, in a directory). The diagram below illustrates 
the IOS_DIR_$ENTRY_T data type: 
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predefined 
type 


byte: 
offset 

0: 

2: 

4: 

8: 

12: 

16: 

20: 

24: 

28: 

32: 

36: 

40: 






field name 




integer 




enttype 




integer 


entlen 


name_$name_t 


character array 


entname 




character array 






character array 






character array 






character array 






character array 






character array 






character array 






integer 


unusedl 




integer 


unused2 



Field Description: 

enttype 

The type of directory entry. The value 1 

indicates a file; the value 3 indicates a link. 

entlen 

Length of the name of the entry. 

entname 

Name of the entry. 

unusedl 

Reserved for future use. 



IOS _DIR _ $MODE_T 
STATUS $T 



unused2 

Reserved for future use. 

Reserved for internal use. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 
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byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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IOS_DIR_$ISA 

IOS_DIR_$ISA 

Determines whether an open stream is associated with an object that is a directory. 

FORMAT 

IOS_DIR_$ISA (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Stream ID for an open stream, in ios_$id_t format. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
IOS_DIR Data Types section for more information. 

USAGE 

The ios_dir_$isa call determines whether the IOS_DIR trait is implemented for an object 
to which you have an open stream. If this trait is implemented, then the object must be a 
directory. Therefore, you can use the ios_dir_$isa call to determine whether a particular 
stream ID is associated with an object that is a directory. 
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IOS_DIR_$OPEN 

Opens a stream connection to an object in a currently open directory. 

FORMAT 

stream-id = IOS_DIR_$OPEN (dir-id, leaf-name, leaf-namelen, open-options, 
status) 

RETURN VALUE 

stream- id 

Stream ID for the stream to the object, in ios_$id_t format. This is a 2-byte integer. 

INPUT PARAMETERS 

dir-id 

Stream ID for the stream to the directory that contains the object, in ios_$id_t format. 
This is a 2-byte integer. 

leaf-name 

Name of the object to open, relative to the directory associated with dir-id parameter, in 
pname_$name_t format. This is an array of up to name _$pnamlen_ max (256) 
characters. The object must be an element in the specified directory, not in a subdirectory. 

leaf-namelen 

Length of the leaf-name. This is a 2-byte integer. 

open- options 

A set (bitmask) of options, in ios_$open_ options _t format. This is a 2-byte integer. 
Specify one or more of the following predefined values: 

IOS _ $INQUIRE _ ONLY_ OPT 

Open the object for attribute inquires only; do not permit reading or 
writing of data. 

IOS _ $NO _ OPEN_DELAY_ OPT 

Return immediately, instead of waiting for the open call to complete. 

IOS_$POSITION_TO_EOF_OPT 

Position the stream marker to the end of the object (EOF). 

IOS _ $READ _ INTEND _ WRITE _ OPT 

Open the object for read access with the intent to eventually change to 
write access. This allows other processes to read the object, but they 
cannot have write or read-intend-write access. 

IOS _ $UNREGULATED _ OPT 

Permit shared (unregulated) concurrency mode. 

IOS_$WRITE_OPT 

Permit writing to the object. 
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status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
IOS _ DIR Data Types section for more information. 



USAGE 

This call lets you open an object by specifying its name relative to a currently open 
directory. For example, if you have already opened the directory //barn/animals, you can 
use ios_dir_$open to open an object named horse (in this directory). To do this, specify 
the stream ID for the directory and the leaf name horse. Note that when you use 
ios_dir_$open, you must specify the name of a leaf in the specified directory, not in a 
subdirectory. 
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ERRORS 






STATUS _$OK 

Successful completion. 
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The IPC (Interprocess Communications) programming calls perform interprocess communications 
using datagrams addressed to destinations identified with file system names. This section 
describes their data types, call syntax, and error codes. Refer to the Introduction at the 
beginning of this manual for a description of data-type diagrams and call syntax format. 
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IPC DATA TYPES 



DATA TYPES 



IPC $DATA T 



IPC $HDR INFO T 



IPC $SOCKET HANDLE T 



An array of up to 1024 characters. The data 
portion of an IPC datagram. 

An array of up to 128 characters. The header 
portion of an IPC datagram. 

An array of 20 characters. A handle for an IPC 
socket. 



NAME $PNAME T 



STATUS $T 



An array of up to 256 characters. A DOMAIN 
pathname. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 

23). 
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Ocode 
A signed number that identifies the type of error 
that occurred (bits - 15). 



o 



IPC-3 IPC 



IPC_$CLOSE 

IPC_$CLOSE 

Closes an IPC socket. 

FORMAT 

IPC_$CLOSE (pathname, length, status) 

INPUT PARAMETERS 

pathname 

Pathname for the file where the socket handle is stored, in NAME_$PNAME_T format. 
This is an array of up to 256 characters. Specify a file that was created by a previous 
IPC _$CREATE call. 

length 

Length of the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

IPC_$CLOSE closes a socket and removes its handle from the file where the handle is 
stored. IPC_$CLOSE does not, however, delete the socket handle file. To delete this file, 
use IPC $DELETE. 
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IPC_$CREATE 

IPC_$CREATE 

Creates a file where an IPC socket handle can be stored. 

FORMAT 

IPC_$CREATE (pathname, length, status) 

INPUT PARAMETERS 

pathname 

Pathname for a file where a socket handle can be stored, in NAME_$PNAME_T format. 
This is an array of up to 256 characters. 

length 

Length of the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

IPC_$CREATE creates a special type of DOMAIN system object that is used only for 
socket handles. When you open a socket, the system obtains a handle for the socket and 
stores this handle in the file that you specify. You can open a socket only if you have 
previously used IPC_$CREATE to create a file for the handle. 
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IPC_$DELETE 

Deletes a file that was used to store an IPC socket handle. 

FORMAT 

IPC_$DELETE (pathname, length, status) 

INPUT PARAMETERS 

pathname 

Pathname for the file where the socket handle was stored, in NAME _ $PNAME _ T format. 
This is an array of up to 256 characters. 

length 

Length of the pathname. This is a 2- byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

IPC_$DELETE deletes a file that the system used to store a handle for an open socket. 
You must call IPC_$CLOSE to close the socket before you can delete the file containing 
the socket's handle. 
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IPC_$GET_EC 

Gets a pointer to the eventcount associated with an IPC socket. 

FORMAT 

IPC_$GET_EC (handle, ec-ptr. status) 

INPUT PARAMETERS 

handle 

Handle for the socket whose eventcount you are getting, in IPC_$SOCKET_HANDLE_T 
format. This is an array of 20 characters. 

OUTPUT PARAMETERS 

ec-ptr 

Pointer to the eventcount, in EC2_$PTR_T format. This is a 4-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

IPC_$GET_EC gets a pointer to the eventcount associated with an IPC socket. You can 
use this eventcount to wait for incoming datagrams. Use EC2 system calls to read the 
eventcount value and wait for datagrams. 

IPC_$GET_EC is useful when you want to wait for messages arriving in more than one 
socket. To wait for messages from only one socket, use IPC_$WAIT or IPC_$SAR. 
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IPC_$OPEN 

IPC_$OPEN 

Opens an available IPC socket, obtains its handle, and places the handle in a file. 

FORMAT 

IPC_$OPEN (pathname, length, depth, handle, status) 

INPUT PARAMETERS 

pathname 

Pathname for the file in which to store the handle, in NAME_$PNAME_T format. This 
is an array of up to 256 characters. Specify a file that you have created with a previous 
IPC _$CREATE call. 

length 

Length of the pathname. This is a 2-byte integer. 

depth 

Depth of the socket. The depth defines how many datagrams a socket can hold. Allowable 
values are one through four. 

OUTPUT PARAMETERS 

handle 

Handle for the open socket, in IPC_$SOCKET_HANDLE_T format. This is an array of 
20 characters. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

IPC_$OPEN opens an available IPC socket on your program's local node. In addition, 
IPC_$OPEN places the socket's handle in the file you specify. After opening a socket, you 
can receive datagrams in it. A program must use your socket's handle to send you a 
message. 

User programs running on a node can open a maximum of eight sockets on that node. Only 
one program at a time can open any socket. 

You must use IPC_$CREATE to create a file for the socket handle before you can open a 
socket. 
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IPC $RCV 



Gets a datagram that has been received in an IPC socket. This call copies the datagram to 
the buffers that you specify. 



FORMAT 

IPC_$RCV (handle, hdr-buflen, data-buflen, from-handle, 

hdr-buf, hdr-length, data-buf, data-length, status) 



INPUT PARAMETERS 

handle 

Handle for the socket that received the datagram, in IPC _$SOCKET_ HANDLE _T 
format. This is an array of 20 characters. 

hdr-buflen 

Length of the buffer where the datagram header will be copied. This is a 2-byte integer. 
This value defines the maximum number of header bytes that IPC_$RCV will get. An IPC 
datagram can contain up to 128 header bytes. Specify a length that can accommodate the 
longest header you expect to receive. 

data-buflen 

Length of the buffer where the data portion of the datagram will be copied. This is a 
2-byte integer. This value defines the maximum number of data bytes that IPC_$RCV 
will get. The data portion of an IPC datagram can contain up to 1024 bytes. Specify a 
length that can accommodate the longest data you expect to receive. 

OUTPUT PARAMETERS 

from- handle 

Handle for the socket where the datagram originated, in IPC _$SOCKET_ HANDLE _T 
format. This is an array of 20 characters. Use this handle to send a reply to the datagram 
you are currently getting. 

hdr-buf 

Buffer where the datagram header is copied. This buffer can contain up to 128 bytes. 

hdr-length 

Length, in bytes, of the header that is copied. This is a 2-byte integer. 

data-buf 

Buffer where the data portion of the datagram is copied. This buffer can contain up to 1024 
bytes. 

data- length 

Length, in bytes, of the data that is copied. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 
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IPC_$RCV gets datagrams that have been received in a socket and copies them to your 
buffers. This call returns only the number of header and data bytes that you specify, even 
if the actual datagram (in the socket) contains more bytes. 

IPC_$RCV gets datagrams in the order in which they arrive in the socket queue. If the * 
socket queue is full when an incoming datagram arrives, the datagram is lost. You can use 
IPC_$RCV to get datagrams only from a socket that you have previously opened with 
IPC_$OPEN. 

Usually, you wait for a datagram to arrive in a socket, and then call IPC_$RCV to get the 
datagram. If you call IPC_$RCV when the socket is empty, the call returns immediately 
with the status IPC $SOCKET EMPTY. 



v_.- 



IPC IPC- 10 



o 



o 



IPC_$RESOLVE 

IPC_$RESOLVE 

Obtain the handle for an open socket. 

FORMAT 

IPC_$RESOLVE (pathname, length, handle, status) 

INPUT PARAMETERS 

pathname 

Pathname for the file containing the socket handle, in NAME_$PNAME_T format. This 
is an array of up to 256 characters. Specify a file that was created by a previous 
IPC_$CREATE call. 

length 

Length of the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

handle 

Handle for the socket, in IPC _$SOCKET_ HANDLE _T format. This is an array of 20 
characters. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

IPC_$RESOLVE returns the handle associated with an open socket. Use this call if you 
know a socket's pathname, but you need the socket handle to send a datagram. 

IPC_$RESOLVE returns the error IPC _$SOCKET_ NOT _ OPEN if the handle file does 
not contain the handle for an open socket. 
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IPC_$SAR 

Performs a single send/await-reply operation. This call sends a datagram, waits a specified 
amount of time for a reply, and copies the reply to the buffers you specify. 

FORMAT 

IPC_$SAR (re try-time, to-handle, in-hdr-buf, in-hdr-length, in-data-buf , 
in-data-length, out-hdr-buf len, out-data-buf len, out-hdr-buf , 
out-hdr-length, out-data-buf, out-data-length, status) 

INPUT PARAMETERS 

retry- time 

Number of quarter-seconds to wait for a reply. This is a 2-byte integer. 

to-handle 

Handle for the destination socket, in IPC_$SOCKET_HANDLE_T format. This is an 
array of 20 characters. The destination socket is where you are sending the datagram. 

in-hdr-buf 

Buffer that contains the header for the datagram you are sending. This buffer can contain 
up to 128 bytes. 

in-hdr-length 

Length, in bytes, of the header you are sending. This is a 2-byte integer. 

in-data-buf 

Buffer that contains the data portion of the datagram you are sending. This buffer can 
contain up to 1024 bytes. 

in- data- length 

Length, in bytes, of the data you are sending. This is a 2-byte integer. 

out-hdr-buflen 

Length of the buffer where the reply datagram header will be copied. This is a 2-byte 
integer. This value defines the maximum number of header bytes that JPC_$SAR will get 
from the reply datagram. The reply can contain up to 128 header bytes. Specify a length 
that can accommodate the longest header you expect to receive. 

out- data- buf len 

Length of the buffer where the data portion of the reply datagram will be copied. This is a 
2-byte integer. This value defines the maximum number of data bytes that IPC_$SAR 
will get from the reply datagram. The data portion of a reply can contain up to 1024 
bytes. Specify a length that can accommodate the longest data you expect to receive. 

OUTPUT PARAMETERS 

out-hdr-buf 

Buffer where the header for the reply datagram is copied. This buffer can contain up to 
128 bytes. 

out- hdr- length 

Length, in bytes, of the header that is copied. This is a 2-byte integer. 
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out- data-buf 

Buffer where the data portion of the reply datagram is copied. This buffer can contain up 
to 1024 bytes. 

out- data- length 

Length, in bytes, of the data that is copied. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

Use IPC_$SAR to send a datagram to another process and wait a specified time for a 
reply. If the reply datagram does not arrive within the specified time, EPC_$SAR returns 
the status code IPC_$TIMEOUT. 

IPC_$SAR returns only the number of header and data bytes that you specify, even if the 
actual datagram (in the socket) contains more bytes. 

When you send a datagram that contains less than 128 bytes of information, you can place 
all the information in the header buffer. Then specify the data length as zero. It takes less 
time to send a datagram that contains only a header. 
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IPC_$SEND 

Sends a datagram to an IPC socket. 

FORMAT 

IPC_$SEND (to-handle, reply-handle. hdr-t>uf. hdr-length, 
data-buf, data-length, status) 

INPUT PARAMETERS 

to- handle 

Handle for the destination socket, in IPC_$SOCKET_HANDLE_T format. This is an 
array of 20 characters. The destination socket is where you are sending the datagram. 

reply-handle 

Handle for the reply socket, in IPC _$SOCKET_ HANDLE _T format. This is an array of 
20 characters. The reply socket is where you can receive a reply. 

hdr-buf 

Buffer that contains the header for the datagram you are sending. This buffer can contain 
up to 128 bytes. 

hdr- length 

Length, in bytes, of the datagram header. This is a 2-byte integer. 

data-buf 

Buffer that contains the data portion of the datagram you are sending. This buffer can 
contain up to 1024 bytes. 

data- length 

Length, in bytes, of the data portion of the datagram. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

IPC_$SEND sends a datagram to the socket that you specify. To obtain a socket handle 
from a pathname, use IPC_$RESOLVE. 

Even if IPC_$SEND completes successfully, there is no guarantee that the datagram will 
be received by the process you are sending it to. The programs using IPC datagrams are 
responsible for verifying that datagrams are successfully received. Note that you can use 
IPC_$SAR to perform a send/await reply operation with a single call. 

When you send a datagram that contains less than 128 bytes of information, you can place 
all the information in the header buffer. Then specify the data length as zero. It takes less 
time to send a datagram that contains only a header. 
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IPC_$WAIT 

Waits for a specified amount of time to receive a datagram in an IPC socket. 

FORMAT 

IPC $WAIT (handle, wait-time, status) 



INPUT PARAMETERS 

handle 

Handle for the socket that you are waiting to receive data in, in 
IPC_$SOCKET_HANDLE_T format. This is an array of 20 characters. 

wait-time 

Number of quarter-seconds to wait for a reply. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the IPC 
Data Types section for more information. 

USAGE 

IPC_$WAlT waits for a specified amount of time to receive a datagram in a socket. If a 
datagram is received before the time elapses, the call returns with the status 
STATUS _$OK. To get the datagram, use E?C_$RCV. 

If IPC_$WAIT times out before a datagram is received, the call returns with the status 
IPC_$TIMEOUT. If you call IPC_$WAIT and there is a datagram already in the socket, 
the call returns immediately with a success status. 

Note that you can use IPC_$SAR to perform a send/await reply operation with a single 
call. Also, if you want to wait for datagrams in more than one socket, use 
IPC_$GET_EC to get pointers to the appropriate eventcounts. Then use eventcount calls 
(EC2) to wait for datagrams. 
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IPC ERRORS 

ERRORS ~" 

IPC_$OK 

Successful completion. 

IPC _ $NOMORE _ SOCKETS 

All the sockets are in use. 

IPC_$NOT_IPC_OBJ 

The specified pathname does not belong to an IPC object. 

IPC _ $NOT _ OWNER 

You did not open the socket so you cannot close it. 

IPC _ $RANGE _ERROR 

Supplied socket number is outside legal range. 

IPC _ $SOCKET _ ALREADY_ OPEN ^-^ 

Specified socket is already open. i 

v, , s 

IPC_$SOCKET_EMPTY 

There are no datagrams in the socket. 

IPC_$SOCKET_ NOT _ OPEN 

The specified socket is not open. 

rPC_$TIMEOUT 

The call timed out before a datagram was received. ^ ^ 

IPC_$TOO_DEEP V 

Supplied socket depth is too big. 

IPC _ $TOO _MUCH _ DATA 

The data is too long to send. 

STATUS _$OK 

Successful completion. 
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The MBX (Mailbox) programming calls perform interprocess communications using virtual 
circuits addressed to destinations identified with pathnames. This section describes their data 
types, call syntax, and error codes. Refer to the Introduction at the beginning of this manual for 
a description of data-type diagrams and call syntax format. 
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MBX DATA TYPES 



CONSTANTS 



MBX $CHN MAX 



MBX_$FIL_MAX 


257* 


MBX_$MIN_CHN_SIZE 


64 


MBX_$MSG_MAX 


1024 


MBX_$MSG_TN 


1023 


MBX_$MSG_WMAX 


512 


MBX $MSG WTN 


511 



255 Maximum number of channels that can be open to 

a mailbox. 

257*32768 Maximum mailbox size. 

The minimum size of a channel buffer. 

A mailbox message that is 1024 bytes long. 

For use when declaring a zero-based array that is 
MBX_$MSG_MAX bytes long. 

A mailbox message that is 512 words long. 

For use when declaring a zero-based array that is 
MBX_$MSG_WMAX words long. 



MBX_$REC_DATA_MAX 32760 

MBX_$REC_MSG_MAX 32766 

MBX_$SERV_MSG_HDR_LEN 6 

MBX_$SERV_MSG_MAX 1030 

MBX $VERSION 1 



The maximum length of the data portion of a 
mailbox message. 

The maximum length of a server message, including 
the header and data portions. 

Length of the mailbox header for a server message. 

A server message that contains 1024 bytes of data 
plus a 6-byte header. 

Current version of MBX. 



DATA TYPES 



EC2_$PTR_T 

MBX $CHAN NUM T 



A 4-byte integer. A pointer to an eventcount. 

A channel number. Possible values are integers 
from through MBX_$CHN_MAX. 
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MBX DATA TYPES 



MBX $CHAN SET T 



A set of channel numbers of type 
MBX_$CHAN_NUM_T. The following Pascal 
example specifies channels 1, 4, and 7: 



VAR 



chan set : mbx $chan set t 



chan set := [ 1, 4, 7] 



o 



MBX $EC KEY T 



In a FORTRAN program, declare an 8-element 
array of 4-byte integers to indicate a channel set. 
Use the array as a mask in which the bits represent 
mailbox channels. 

A 2-byte integer. A mailbox eventcount. One of 
the following predefined values: 



MBX_$GETREC_EC_KEY 

An eventcount that advances when the 

mailbox contains messages for you to get. 



MBX $MTYPE T 



MBX_$PUTREC_EC_KEY 
An eventcount that advances when enough 
room exists in the channel to hold the last 
message you unsuccessfully tried to put there. 

A 2-byte integer. A message type. One of the 
following predefined values: 

MBX_$ACCEPT_OPEN_MT 

A response from a server to accept a client's 

open request. 

MBX_ $CHANNEL _ OPEN_ MT 

A request from a client to open a channel to a 

mailbox. 



MBX_$DATA_MT 
A data transmission. 

MBX_$DATA_PARTIAL_MT 
A partial data transmission. 

MBX_$EOF_MT 

An end of transmission notice. 



MBX $NAME T 



MBX_$REJECT_OPEN_MT 

A response from a server to reject a client's 

open request. 

An array of up to 256 characters. A mailbox name. 



MBX- 3 



MBX 



MBX DATA TYPES 



MBX $MSG HDR T 



A mailbox message header. The diagram below 
illustrates the MBX_$MSG_HDR_T data type: 



predefined 
type 



mbx_$mtype_t 



byte: 



offset 




field name 


0: 


integer 


cnt 


2: 


integer 


mt 


4: 


integer 


chan 


Field Description: 





cnt 

The total number of bytes in the message, 

including the header. 



mt 

A value representing a message type. This value 

is one of the predefined values of type 

MBX_$MTYPE_T. 

chan 

The channel of the client that sent the message, 

or that should receive the message. 
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MBX DATA TYPES 



MBX $SERVER MSG T 



A server message with up to 1024 data bytes. The 
diagram below illustrates the 
MBX_$SERVER_MSG_T data type: 



predefined 
type 



mbx_$mtype_t 



o 



o 



byte: 
offset 






field name 


0: 


integer 


cnt 


2: 


integer 


mt 


4: 


integer 


chan 


6: 


* 


up to 
1024 ^ 
bytes 


data 


Field Description: 





cht 



The total number of bytes in the message, 
including the header. 



mt 



A value representing a message type. This value 
is one of the predefined values of type 
MBX $MTYPE T. 



o 



chan 

The channel of the client that sent the message, 

or that should receive the message. 

data 

The data portion of the message. This field can 

contain up to 1024 bytes. 



MBX- 5 



MBX 



MBX DATA TYPES 



STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



^ 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


1 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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MBX_$CLIENT_WINDOW 

Returns the buffer size for the mailbox that a client is using. 

FORMAT 

size = MBX_$CLIENT_WINDOW (handle, status) 

RETURN VALUE 



size 



O 



Buffer size for the mailbox. This is a 4-byte integer. 

This value defines a window size when a client sends messages to a remote server. That is, 
the client cannot send messages that are larger than the mailbox's buffer. 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX _$ CREATE _ SERVER. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 



o 



When a client sends a message, the message is stored in a channel buffer until the server 
gets the message. The buffer size defines the maximum number of message bytes that the 
channel can hold at one time. 

A client can use MBX _$ CLIENT _ WINDOW to get the size of the channel buffer. To get 
the size, MBX _$ CLIENT _ WINDOW queries the MBX_HELPER on the server's node. 
Note that MBX_$CLIENT_ WINDOW returns the actual buffer size, not the number of 
unused bytes in the buffer. 

MBX _$ CLIENT _ WINDOW only works correctly when the server you are inquiring about 
is on a node with SR9 or later software. If you call MBX _$ CLIENT _ WINDOW and the 
server is on a node with pre-SR9 software, MBX_$CLIENT_ WINDOW returns the value 
1158. This value is returned, even if the mailbox's actual buffer size is smaller. Therefore, 
this call does not provide a reliable way to determine the window size when sending 
messages to a server that is running on a node with pre-SR9 software. 

MBX_$CLIENT_ WINDOW is for use only by mailbox clients. A server should use 
MBX $SERVER WINDOW. 



o 



MBX-7 MBX 



MBX_$CLOSE 

MBX_$CLOSE 

Closes a mailbox or a channel. 

FORMAT 

MBX_$CLOSE (handle, status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$CREATE_ SERVER or MBX_$OPEN. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

Both clients and servers can use MBX_$CLOSE. When called from a client, 
MBX_$CLOSE tells the server that the client is no longer using the channel. When called 
from a server, MBX_$CLOSE closes the mailbox. 

After a client calls MBX_$CLOSE, the server should call MBX_$DEALLOCATE to 
deallocate the channel and free it for use by other clients. No other client can use the 
channel until it has been deallocated by the server. 

If a server closes a mailbox while there are still active clients, the clients get errors on 
subsequent attempts to use the mailbox. 
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MBX_$COND_GET_REC_CHAN 

MBX_ $COND _ GET _ REC _ CHAN 

Attempts to get a mailbox message from a specified channel. 

(* 

FORMAT 

MBX_$COND_GET_REC_CHAN (handle, channel, bufptr, buflen, retptr. retlen. status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
you obtained from MBX_$CREATE_ SERVER. 

channel 

Channel to read from. This is a 2- byte integer. The mailbox manager assigns a channel 
number to a client when the client calls MBX_$OPEN. 

bufptr 

Pointer to a data buffer where the message can be copied. This is a 4-byte integer. 

Your program must allocate a data buffer, although the mailbox manager does not always 
copy messages to this buffer. Use the output parameter retptr to reference the message. 

buflen 

The number of bytes in the data buffer. This is a 4-byte integer. For a server, MBX will 
never return more than 32766 bytes. For a client, MBX will never return more than 32760 
bytes. 

OUTPUT PARAMETERS 

retptr 

Pointer to the buffer where the message is copied. This is a 4-byte integer. 

retlen 

Either the number of bytes in the returned message, or the number of message bytes 
waiting to be returned. This is a 4-byte integer. 

MBX_ $COND_ GET _ REC _ CHAN can get as many bytes as you specify in buflen. If 
the message is less than or equal to buflen, then the call gets the entire message and retlen 
specifies the message length. If the message is greater than buflen, then the call gets the 
number of bytes specified in buflen. If this occurs, then retlen contains a negative value, 
the absolute value of which is the number of bytes remaining in the message. Get the 
remaining data with another call. 

Note that a server sees the message header each time it gets a piece of the message. The 
count field contains the total length of the message ~ not the length of the returned piece. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 
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MBX $COND GET REC CHAN 



USAGE 



MBX_$COND_GET_REC_CHAN requests a message from a specified channel. If there 
is no message, the call returns immediately with the status MBX _$ CHANNEL _ EMPTY. 
You can use an eventcount to tell when the status of the mailbox has changed. You get a 
mailbox eventcount with MBX_$GET_EC. 

Only a server can use MBX_$COND_GET_REC_CHAN. To perform a conditional get 
operation from a client, use MBX_$GET_ CONDITIONAL. 
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MBX_$COND_GET_REC_CHAN_SET 

MBX_$COND_GET_REC_CHAN_SET 

Attempts to get a mailbox record from a set of clients. 

FORMAT 

MBX_$COND_GET_REC_CHAN_SET (handle, chan-set, bufptr, buflen, retptr, retlen, 

status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$ CREATE _ SERVER. 

chan-set 

Set of channels to read from, in MBX_$CHAN_SET_T format. This is an 8-element 
array of 4-byte integers. See the MBX Data Types section for more information. 

The mailbox manager assigns a channel number to a client when the client calls 
MBX_$OPEN. The channel number can range from 1 through MBX_$CHN_MAX. 

bufptr 

Pointer to a data buffer whe\re the message can be copied. This is a 4-byte integer. 

Your program must allocate a data buffer, although the mailbox manager does not always 
copy messages to this buffer. Use the output parameter retptr to reference the message. 

buflen 

Number of bytes in the data buffer. This is a 4-byte integer. For a server, MBX will never 
return more than 32766 bytes. For a client, MBX will never return more than 32760 bytes. 

OUTPUT PARAMETERS 

retptr 

Pointer to the buffer where the message is copied. This is a 4-byte integer. 

retlen 

Either the number of bytes in the returned message, or the number of message bytes 
waiting to be returned. This is a 4-byte integer. 

MBX_$COND_GET_REC_CHAN_SET can get as many bytes as you specify in 
buflen. If the message is less than or equal to buflen, then the call gets the entire message 
and retlen specifies the message length. If the message is greater than buflen, then the call 
gets the number of bytes specified in buflen. If this occurs, then retlen contains a negative 
value, the absolute value of which is the number of bytes remaining in the message. Get 
the remaining data with another call. 

Note that a server sees the message header each time it gets a piece of the message. The 
count field contains the total length of the message ~ not the length of the returned piece. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 
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USAGE r 

MBX_$COND_GET_REC__CHAN_SET requests a message from a specified set of 
channels. If there is no message, the call returns immediately with the status 
MBX_$CHANNEL_EMPTY. You can use an eventcount to tell when the status of the 
mailbox has changed. You get a mailbox eventcount with MBX_$GET_EC. 

Only a mailbox server can use this call. To perform a conditional get operation from a 
client, use MBX_$GET_ CONDITIONAL. 
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MBX_$CREATE_SERVER 

MBX_ $CREATE _ SERVER 

Creates and opens a server's mailbox. 

FORMAT 

MBX_$CREATE_SERVER (name, namelen, bufsize, maxchan, handle, status) 

INPUT PARAMETERS 

name 

Name of the mailbox, in MBX_$NAME_T format. This is an array of up to 256 
characters. Specify the name as a pathname to the mailbox file. If you use the name of a 
file that already exists, this call deletes the contents of the file. If the file already exists and 
it is in use, then the call returns an error. 

namelen 

Number of characters in the name. This is a 2-byte integer. 

bufsize 

Number of message bytes that the server and client can each store in a channel. This is a 
2-byte integer. You must specify a buffer size of at least MBX_$MIN_CHN_SIZE (64 
bytes). This allocates 128 bytes for each channel -- 64 bytes apiece for the server and the 
client buffers. The maximum buffer size is 32766. If you specify an odd numbered buffer 
size, it is rounded down to an even number. 

The buffer size should be large enough to store the largest message you plan to send from a 
server or a client. Note that the maximum message length is MBX_$REC_MSG_MAX 
(32766), which includes 32760 data bytes plus a 6-byte header. If you specify a buffer size 
of less than MBX_$REC_MSG_MAX, you impose a lower limit on the total length of 
messages that pass through the mailbox. 

Note that if you specify a buffer size that is greater than 1158, and the server is 
communicating with clients on remote nodes, the length of the transmitted messages may be 
limited by the MBX_HELPER on the client node. When a server puts a message into the 
mailbox and the message is intended for a remote client, the message passes through the 
system mailbox maintained by the remote node's MBX_HELPER. By default, this 
mailbox has a buffer size of 1158 bytes. To allow the remote node's mailbox to handle 
larger messages, use the -DATASIZE option to specify a larger buffer size when you start 
the MBX_ HELPER. Specify a value that is at least as large as the largest message the 
server will send. 

maxchan 

Maximum number of channels that can be simultaneously open to the mailbox. This is a 
2-byte integer. You can allow up to MBX_$CHN_MAX (255) channels. 

OUTPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Subsequent 
calls use this handle to send and receive messages. 
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status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

A server uses MBX _$ CREATE _ SERVER to create a mailbox. Once the mailbox is open, 
clients use MBX_$OPEN to open communications channels to the mailbox. 

In a secure network, a mailbox gets an access control list (ACL) that is determined by the 
ACL of the directory in which the mailbox is created. If servers and clients on different 
nodes use the mailbox, be sure that the server's MBX_HELPER has read and write access 
to the mailbox. 
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MBX_ SDEALLOCATE 

MBX_ $DEALLOCATE 

Releases a channel for use by another client. 

FORMAT 

MBX_$DEALLOCATE (handle, channel, status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4- byte integer. Use the handle 
returned by MBX_$CREATE_ SERVER. 

channel 

Channel to deallocate. This is a 2-byte integer. The mailbox manager assigns a channel 
number to a client when the client calls MBX $OPEN. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

Only a server can call MBX _$DEALLO GATE. A client uses MBX_$CLOSE to indicate 
the end of transmission over a channel. However, the server must deallocate the channel 
before another client can use it. 

A server can deallocate a channel while a client is still using it; this both closes and 
deallocates the channel. The next time the client tries to use the channel, the client receives 
the error MBX $CHANNEL NOT OPEN. 
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MBX_$GET_CONDITIONAL 

MBX_$GET_CONDITIONAL ^-^ 

i 
Attempts to get a mailbox message. v_.y 

FORMAT 

MBX_$GET_CONDITIONAL (handle, bufptr, buflen, retptr, retlen, status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$CREATE_ SERVER or MBX_$OPEN. 

bufptr 

Pointer to a data buffer where the message can be copied. This is a 4-byte integer. 

Your program must allocate a data buffer, although the mailbox manager does not always f ^ 

copy messages to this buffer. Use the output parameter retptr to reference the message. K ^_y 

buflen 

Number of bytes in the data buffer. This is a 4-byte integer. For a server, MBX will never 
return more than 32766 bytes. For a client, MBX will never return more than 32760 bytes. 

OUTPUT PARAMETERS 

retptr 1 

Pointer to the buffer where the message is copied. This is a 4-byte integer. 

retlen 

Either the number of bytes in the returned message, or the number of message bytes 
waiting to be returned. This is a 4-byte integer. 

MBX_$GET_ CONDITIONAL can get as many bytes as you specify in buflen. If the 
message is less than or equal to buflen, then the call gets the entire message and retlen 
specifies the message length. If the message is greater than buflen, then the call gets the 
number of bytes specified in buflen. If this occurs, then retlen contains a negative value, 
the absolute value of which is the number of bytes remaining in the message. Get the 
remaining data with another call. 

Note that a server sees the message header each time it gets a piece of the message. The 
count field contains the total length of the message — not the length of the returned piece. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 
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USAGE 



MBX_$GET_ CONDITIONAL gets a message if one is waiting. Otherwise, the call 
returns immediately with a completion status of MBX_$CHANNEL_ EMPTY. You can 
use an eventcount to tell when the status of the mailbox has changed. You get a mailbox 
eventcount with MBX_$GET_EC. 

Both servers and clients can use MBX_$GET_ CONDITIONAL. When a server calls 
MBX_$GET_ CONDITIONAL, the mailbox manager uses a scheduling algorithm to 
determine the channels to search for the next message. This algorithm guarantees fair 
service to each open channel. 



O 
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MBX_$GET_EC 

MBX_$GET_EC 

Get pointer to eventcount for mailbox event mbx 

FORMAT 

MBX_$GET_EC (mbx-handle. mbx-key, eventcount-pointer, status) 

INPUT PARAMETERS 

mbx-handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$CREATE_ SERVER or MBX_$OPEN. 

mbx- key 

Type of eventcount to get a pointer to, in MBX_$EC_KEY_T format. This is a 2-byte 
integer. Specify one of these predefined values: 

MBX_ $GETREC _EC _KEY 

An eventcount that advances when the mailbox may contain 
messages for you to get. For a server, this eventcount may 
advance whenever there is anything to get from any open 
channel. 

MBX_ $PUTREC _EC _KEY 

An eventcount that advances when there may be enough room 
in the channel to hold the last message you unsuccessfully tried 
to put there. A mailbox server sees only one 
MBX_$PUTREC_EC_KEY eventcount for the entire 
mailbox. If puts fail with 

MBX_ $NO _ROOM _ IN _ CHANNEL on two channels of the 
same mailbox, the event's completion simply says that at least 
one channel may now take the message. One or both channels 
may now be capable of taking the respective message. 

OUTPUT PARAMETERS 

eventcount-pointer 

A pointer to an eventcount, in EC2_$PTR_T format. This is a 4-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

After you use MBX_$GET_EC to get a mailbox eventcount, use EC2 calls to read 
eventcount values and wait for events. 
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MBX_$GET_REC 

MBX_$GET_REC 

Gets a message from a mailbox. 

FORMAT 

MBX_$GET_REC (handle, bufptr, buflen. retptr, retlen, status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$CREATE_ SERVER or MBX_$OPEN. 

bufptr 

Pointer to a data buffer where the message can be copied. This is a 4-byte integer. 

Your program must allocate a data buffer, although the mailbox manager does not always 
copy messages to this buffer. Use the output parameter retptr to reference the message. 

buflen 

Number of bytes in the data buffer. This is a 4-byte integer. For a server, MBX will never 
return more than 32766 bytes. For a client, MBX will never return more than 32760 bytes. 

OUTPUT PARAMETERS 

retptr 

Pointer to the buffer where the message is copied. This is a 4-byte integer. 

retlen 

Either the number of bytes in the returned message, or the number of message bytes 
waiting to be returned. This is a 4-byte integer. 

MBX_$GET_REC can get as many bytes as you specify in buflen. If the message is less 
than or equal to buflen, then the call gets the entire message and retlen specifies the 
message length. If the message is greater than buflen, then the call gets the number of 
bytes specified in buflen. If this occurs, then retlen contains a negative value, the absolute 
value of which is the number of bytes remaining in the message. Get the remaining data 
with another call. 

Note that a server sees the message header each time it gets a piece of the message. The 
count field contains the total length of the message — not the length of the returned piece. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 
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USAGE 

MBX_$GET_REC gets a mailbox message. If there is no message in the mailbox, the call 
waits for one. 

Both servers and clients can use MBX_$GET_REC. When a server calls 
MBX_$GET_REC, the mailbox manager uses a scheduling algorithm to determine the 
channel to search for the next message. This algorithm guarantees fair service to each open 
channel. 
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MBX_$GET_REC_CHAN 

MBX_$GET_REC_CHAN 

Gets a mailbox message from a specified channel. 

FORMAT 

MBX_$GET_REC_CHAN (handle, channel, bufptr, buflen, retptr, retlen, status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_ $ CREATE _ SERVER. 

channel 

Channel to read from. This is a 2-byte integer. The mailbox manager assigns a channel 
number to a client when the client calls MBX_$OPEN. 

bufptr 

Pointer to a data buffer where the message can be copied. This is a 4-byte integer. 

Your program must allocate a data buffer, although the mailbox manager does not always 
copy messages to this buffer. Use the output parameter retptr to reference the message. 

buflen 

Number of bytes in the data buffer. This is a 4-byte integer. For a server, MBX will never 
return more than 32766 bytes. For a client, MBX will never return more than 32760 bytes. 

OUTPUT PARAMETERS 

retptr 

Pointer to the buffer where the message is copied. This is a 4-byte integer. 

retlen 

Either the number of bytes in the returned message, or the number of message bytes 
waiting to be returned. This is a 4-byte integer. 

MBX_$GET_REC_CHAN can get as many bytes as you specify in buflen. If the message 
is less than or equal to buflen, then the call gets the entire message and retlen specifies the 
message length. If the message is greater than buflen, then the call gets the number of 
bytes specified in buflen. If this occurs, then retlen contains a negative value, the absolute 
value of which is the number of bytes remaining in the message. Get the remaining data 
with another call. 

Note that a server sees the message header each time it gets a piece of the message. The 
count field contains the total length of the message — not the length of the returned piece. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 
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USAGE 



MBX_$GET_REC_CHAN requests a message from the specified mailbox and channel. 
If there is no message, the call waits for one. Only a mailbox server can use this call. To 
perform a get operation from a client, use MBX_$GET_REC. 
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MBX_$GET_REC_CHAN_SET 

Gets a mailbox message from a specified set of channels. 

FORMAT 

MBX_$GET_REC_CHAN_SET (handle, chan-set, bufptr. buflen. retptr. retlen. status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$CREATE_ SERVER. 

chan-set 

Set of channels to read from, in MBX_$CHAN_SET_T format. This is an 8-element 
array of 4-byte integers. See the MBX Data Types section for more information. 

The mailbox manager assigns a channel number to a client when the client calls 
MBX_$OPEN. The channel number can range from 1 through MBX_$CHN_MAX. 

bufptr 

Pointer to a data buffer where the message can be copied. This is a 4-byte integer. 

Your program must allocate a data buffer, although the mailbox manager does not always 
copy messages to this buffer. Use the output parameter retptr to reference the message. 

buflen 

Number of bytes in the data buffer. This is a 4-byte integer. For a server, MBX will never 
return more than 32766 bytes. For a client, MBX will never return more than 32760 bytes. 

OUTPUT PARAMETERS 

retptr 

Pointer to the buffer where the message is copied. This is a 4-byte integer. 

retlen 

Either the number of bytes in the returned message, or the number of message bytes 
waiting to be returned. This is a 4-byte integer. 

MBX_$GET_REC_CHAN_SET can get as many bytes as you specify in buflen. If the 
message is less than or equal to buflen, then the call gets the entire message and retlen 
specifies the message length. If the message is greater than buflen, then the call gets the 
number of bytes specified in buflen. If this occurs, then retlen contains a negative value, 
the absolute value of which is the number of bytes remaining in the message. Get the 
remaining data with another call. 

Note that a server sees the message header each time it gets a piece of the message. The 
count field contains the total length of the message — not the length of the returned piece. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 
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USAGE f 

MBX_ $GET_REC_ CHAN _ SET requests a message from the specified mailbox and set ^- 

of channels. If there is no message, the call waits for one. Only a mailbox server can use 
this call. To perform a get operation from a client, use MBX_$GET_REC. 

A group of calls is available for manipulating large sets. The calls are: LIB_$INIT_SET, 
LDB_$ADD_TO_SET, LIB _$CLR_ FROM _ SET, and LIB_$MEMBER_OF_SET. 
The calls are fully described in Programming with General System Calls. 
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MBX_$OPEN 

Opens a client channel to a mailbox. 

FORMAT 

MBX_$OPEN (name, namelen, bufptr, buflen, handle, status) 

INPUT PARAMETERS 

name 

Name of the mailbox, in MBX_$NAME_T format. This is an array of up to 256 
characters. Specify the name as a pathname to the mailbox created by the server. 

namelen 

Number of characters in the name. This is a 2-byte integer. 

bufptr 

Pointer to a buffer containing data to be sent with the open request. This is a 4-byte 
integer. If you are not sending data, specify a nil pointer. 

buflen 

Number of bytes of data you are sending. This is a 4-byte integer. If you are not sending 
data, specify a length of 0. 

The maximum amount of data you can send with MBX_$OPEN is MBX_$MSG_MAX 
(1024) bytes, even if the mailbox message buffer is larger. 

OUTPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Subsequent 
calls use this handle to send and receive messages. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

MBX_$OPEN opens a channel from a client to an existing mailbox. Only a client can use 
this call. 

This call makes the mailbox manager send the server a channel open request. The server 
must respond by accepting or rejecting the request. After the server responds, 
MBX_$OPEN returns a status code indicating whether the call was successful. The client 
does not see the acceptance or rejection as a message, but as the completion status of the 
MBX $OPENcall. 
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MBX_$PUT_CHR 

Sends a partial message from a client. 

FORMAT 

MBX_$PUT_CHR (handle, bufptr, buflen, status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$OPEN. 

bufptr 

Pointer to the buffer that contains the message to be sent. This is a 4-byte integer. 

buflen 

Length of the message, in bytes. This is a 4-byte integer. For a client, the buffer can 
contain up to 32760 bytes. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

MBX_$PUT_CHR is equivalent to MBX_$PUT_REC, except that MBX_$PUT_CHR 
informs the server that the message is a partial message. If the mailbox is full, this call 
waits until the mailbox has room for the message. 

Only a client can call MBX_$PUT_CHR. A server can send a partial data message by ( 

using MBX_$PUT_REC or MBX_$PUT_REC_COND, and specifying a message type V. 

of MBX_$DATA_PARTIAL_MT. When the client gets such a message, the get call 
returns a status of MBX $PARTIAL RECORD to the client. 
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MBX_$PUT_CHR_COND 

Attempts to send a partial message from a client. 

FORMAT 

MBX_$PUT_CHR_COND (handle, bufptr. buflen. status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$OPEN. 

bufptr 

Pointer to the buffer that contains the message to be sent. This is a 4-byte integer. 

buflen 

Length of the message, in bytes. This is a 4-byte integer. For a client, the buffer can 
contain up to 32760 bytes. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

MBX_$PUT_CHR_COND is equivalent to MBX_$PUT_REC_COND, except that 
MBX_$PUT_CHR_COND informs the server that the message is a partial message. 

If the client's buffer is full, MBX_$PUT_CHR_COND returns immediately with a 
completion status of MBX _$NO_ ROOM _ IN _ CHANNEL. You can use an eventcount 
to tell when the status of the mailbox eventcount has changed. You get a mailbox 
eventcount with MBX_$GET_EC. 

Only a client can call MBX_$PUT_CHR_COND. A server can send a partial data 
message by using MBX_$PUT_REC or MBX_$PUT_REC_COND, and specifying a 
message type of MBX _$DATA_ PARTIAL _MT. When the client gets such a message, 
the get call returns a status of MBX _$PARTIAL_ RECORD to the client. 
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MBX_$PUT_REC 

Puts a record in the mailbox. 

FORMAT 

MBX_$PUT_REC (handle, bufptr, buflen, status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX _$ CREATE _ SERVER or MBX_$OPEN. 

bufptr 

Pointer to the buffer that contains the message to be sent. This is a 4-byte integer. 

buflen V. 

Length of the message, in bytes. This is a 4-byte integer. For a server, the message can 
contain up to 32766 bytes. For a client, the buffer can contain up to 32760 bytes. 

If a server puts a message that is larger than 1158 bytes, and the client is on a remote node, 
the client node's MBX_ HELPER must be able to handle the message. To handle the 
message, the client node's MBX_HELPER must have a queue data size that is at least as 
large as the message. Use MBX_ $ SERVER _ WINDOW to determine the client node's 
queue data size. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

This call can be used by either servers or clients. Note, however, that servers and clients 
have different message formats. A server must include the 6-byte message header when 
sending a message. In contrast, a client sends only data. 

If the channel is full, this call waits until there is room for the message. 
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MBX_$PUT_REC_COND 

MBX_$PUT_REC_COND 

Attempts to put a message into a mailbox. 

FORMAT 

MBX_$PUT_REC_COND (handle, bufptr, buflen, status) 

INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_$CREATE_ SERVER or MBX_$OPEN. 

bufptr 

Pointer to the buffer that contains the message to be sent. This is a 4-byte integer. 

buflen 

Length of the message, in bytes. This is a 4-byte integer. For a server, the message can 
contain up to 32766 bytes. For a client, the buffer can contain up to 32760 bytes. 

If a server puts a message that is larger than 1158 bytes, and the client is on a remote node, 
the client node's MBX_HELPER must be able to handle the message. To handle the 
message, the client node's MBX_HELPER must have a queue data size that is at least as 
large as the message. Use MBX_ $ SERVER _ WINDOW to determine the client node's 
queue data size. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

MBX_$PUT_REC__COND can be used by either servers or clients. Note, however, that 
servers and clients have different message formats. A server must include the 6-byte 
message header when sending a message. In contrast, a client sends only data. 

If the channel is full, MBX_$PUT_REC_COND returns immediately, with a completion 
status of MBX_$NO_ROOM_IN_ CHANNEL. You can use an eventcount to tell when 
the status of the mailbox eventcount has changed. You get a mailbox eventcount with 
MBX $GET EC. 
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MBX $SERVER WINDOW 



Returns the buffer size for the mailbox maintained by the MBX_ HELPER on a remote 
client's node. 



FORMAT 

size = MBX $SERVER WINDOW (handle, channel, status) 



RETURN VALUE 



size 



Buffer size for the mailbox maintained by the MBX_HELPER on the remote client's node. 
This is a 4-byte integer. 

This value defines a window size when a server sends messages to a remote client. That is, 
the server cannot send messages that are larger than the buffer for the remote 
MBX HELPER'S mailbox. 



INPUT PARAMETERS 

handle 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Use the handle 
returned by MBX_ $ CREATE _ SERVER. 

channel 

Channel belonging to the client whose window size you are inquiring about. This is a 
2-byte integer. The mailbox manager assigns a channel number to a client when the client 
calls MBX $OPEN. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

When a server puts a message into a mailbox and the message is intended for a client on a 
remote node, the message must pass through a system mailbox maintained by the client 
node's MBX_HELPER. Thus, the largest message that a server can send depends on the 
buffer size for the remote client's system mailbox. This buffer size was defined when the 
client node's MBX_HELPER was started. (The MBX_HELPER's -DATASIZE option 
defines a buffer size for the system mailbox.) 

A server can use MBX _$ SERVER _ WINDOW to determine the buffer size for the remote 
client's system mailbox. To get this value, MBX_$SERVER_ WINDOW queries the 
MBX_HELPER on the client's node. Note that MBX_$SERVER_ WINDOW returns the 
actual buffer size, not the number of unused bytes in the buffer. 
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MBX $SERVER WINDOW 



Note that if a server is communicating with clients on different nodes, the buffer size can 
differ on each node. Therefore, the server must use MBX _$ SERVER _ WINDOW to 
obtain the buffer size on each node. 

MBX_$SERVER_ WINDOW correctly returns the buffer size for clients on nodes with 
SR9 or later software. However, if you call MBX _$SERVER_ WINDOW and the specified 
client is on a pre-SR9 node, then the call always returns the value 1158. 1158 is the 
minimum buffer size for mailboxes maintained by pre-SR9 MBX_HELPERs. 

MBX_$SERVER_ WINDOW is for use only by mailbox servers. A client should use 
MBX $CLIENT WINDOW. 
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MBX_ $TIMED _ OPEN 

MBX_ $TIMED _ OPEN 

Attempts to open a client channel to a mailbox within a specified time period. V — / 

FORMAT 

MBX_$TIMED_OPEN (name, namelen, bufptr, buflen, wait-time, handle, status) 

INPUT PARAMETERS 

name 

Name of the mailbox, in MBX_$NAME__T format. This is an array of up to 256 
characters. Specify the name as a pathname to the mailbox created by the server. 

namelen 

Number of characters in the name. This is a 2-byte integer. 

bufptr 

Pointer to a buffer containing data to be sent with the open request. This is a 4-byte 
integer. If you are not sending data, specify a nil pointer. 

buflen 

Number of bytes of data you are sending. This is a 4-byte integer. If you are not sending 
data, specify a length of 0. 

The maximum amount of data you can send with MBX_$TIMED_OPEN is 
MBX_$MSG_MAX (1024) bytes, even if the mailbox message buffer is larger. 

wait-time 

Time to wait for an open reply, in TIME_$CLOCKH_T format. If you specify a value of 
0, the call will wait forever for an open reply, just like an MBX_$OPEN call. 

OUTPUT PARAMETERS 

handle \ 

Identifier for the mailbox, in UNIV_PTR format. This is a 4-byte integer. Subsequent 
calls use this handle to send and receive messages. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MBX 
Data Types section for more information. 

USAGE 

MBX_$TIMED_OPEN attempts to open a channel from a client to an existing mailbox 
within a specified time period. If the client does not receive a server response within the 
wait- time period, the open fails and the client receives the MBX _$ OPEN _ TIMED _ OUT 
status message. If the server responds after a client open has timed out, it receives the 
MBX_$CHANNEL_ NOT _ OPEN status message. Only a client can use this call. 

No matter what value you specify for wait-time, if no server process is associated with the 
mailbox, the call will fail and return immediately. 
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ERRORS 

MBX_$BAD_KEY 
Bad key. 

MBX_ $BUFFER _ TOO _ SMALL 

A server requested a message using a buffer smaller than 6 bytes. There must be 
enough room for the message header in all server message requests. 

MBX_ $CHANNEL _EMPTY 

There are no messages waiting in the channel. Received in response to an 
MBX_$GET_COND or MBX_$COND_ GET _ CHAN request. 

MBX_ $CHANNEL _ NOT _ OPEN 

For a server, the channel number given referred to a channel that is not presently 
open; for a client, the server has deallocated the client's channel. 

MBX_$CLIENT_NO_RIGHTS 

The client can't access the local MBX_ HELPER'S SYSMBX. 

MBX_ $CLIENT _ SERVER _ DEADLOCK 

A server tried to open a channel to itself; this is illegal. 

MBX_$EOF 

The client has sent a message of type MBX_$EOF_MT. Received in response to an 
MBX_$GET_REC or MBX_$GET_COND request. 

MBX_$FILE_IN_USE 

An MBX_$CREATE_ SERVER or MBX_$OPEN request was made giving a 
mailbox pathname that is the pathname for a file presently in use. 

MBX_$HANDLE_NOT_VALID 

The handle given does not point to a mailbox. 

MBX_ $HELPER _ NO _RIGHTS 

The MBX_HELPER on the server's node can't access the server's mailbox. 

MBX_ $ILL _HANDLE 

The handle given is not a legal handle. 

MBX_$MSG_TOO_BIG_FOR_CHANNEL 

An MBX_$PUT_ CONDITIONAL or MBX_$PUT_REC request tried to send a 
message bigger than the maximum specified when the server created the mailbox. 

MBX_ $NO _MORE _ CHANNELS 

An MBX_$OPEN was made to a mailbox with no free channels. 

MBX_ $NO _MORE _RESOURCES 

An MBX_$CREATE_ SERVER or MBX_$OPEN request was made, and the 
process has insufficient resources left to open the mailbox or the channel. 

MBX_$NO_ROOM_IN_CHANNEL 

There is not enough room in the channel for the message. Received in response to an 
MBX_$PUT_CONDITIONAL request. 

MBX_ $NO _ SERVERS 

An MBX $OPEN was made to a mailbox without an active server. 
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MBX_$OPEN_REJECTED 

The server rejected an MBX _$ OPEN request. 

MBX_ $OPEN_ TIMED _ OUT 

The server did not respond within the specified period of time. 

MBX_ $PARTIAL _RECORD 

Returned data does not contain a complete record. 

MBX_ $RECORD _ LENGTH _ MISMATCH 

A server used one of the MBX_$PUT calls, and the value in the buflen parameter 
did not match the value in the length field of the message header. 

MBX_$REM_RCV_TIMOUT 

A remote operation was attempted, and the network has failed. 

MBX_$REM_SEND_FAILED 

A remote operation was attempted, and the network has failed. 

MBX_ $REM_ SERVICE_UNAVAILABLE 

An MBX_$OPEN open request was made from a remote node when the 
MBX_HELPER program was not running on that node or the server's node. 

MBX_$REMOTE_SERVICE_DENIED 

An MBX_$OPEN request was made from a remote node, and there are not enough 
network services free to handle the request. 

MBX_ $SEQUENCED _ SEND _FAILED 

An internal error occurred while sending a message that is larger than 1158 bytes. 

MBX_$SIZE_TOO_LARGE 

MBX _$ CREATE _ SERVER request asked for a mailbox larger than the maximum. 

MBX_ $SIZE _ TOO _ SMALL 

An MBX_$CREATE_ SERVER request was made with a buffer size smaller than 
the minimum. 

MBX_ $TOO _MANY_ CHANNELS 

An MBX_$CREATE_ SERVER request was made asking for more than the 
maximum number of channels. 

MBX_ $UNEXPECTED _ CNTL _MSG 

Received by a client when the last message the server sent on that channel had a 
message type of MBX_$ACCEPT_OPEN_MT, MBX_$REJECT_OPEN_MT, 
or MBX_$CHANNEL__OPEN_MT when such a message type was inappropriate. 
(MBX_$CHANNEL_OPEN_MT should never be used. The other two message 
types are only used in response to a message of type 

MBX_$CHANNEL_OPEN_MT.) Received in response to an MBX_$GET_REC 
or MBX_$GET_COND request. 

MBX_ $UNKNOWN_RQST 

The client and server are using different versions of the mailbox manager (although 
the two versions have the same version number), and one of them made a request not 
recognized by the other manager. 

MBX_ $ WRONG _ VERSION_ NUMBER 

An MBX_$OPEN request was made using a mailbox manager with a different ( 

version number than the one used to create the mailbox. V — > 
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STATUS _$OK 
' ' Successful completion. 
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The MS (Mapped Segment) programming calls maps to and unmaps from process address space. 
This section describes their data types, call syntax, and error codes. Refer to the Introduction at 
the beginning of this manual for a description of data-type diagrams and call syntax format. 
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MS DATA TYPES 



CONSTANTS 



MS_$EXTEND 

MS $NO EXTEND 



TRUE The object can be extended. 

FALSE The object cannot be extended. 



DATA TYPES 



MS $ACC MODE T 



MS $ACCESS T 



MS_$ADVICE_OPT_T 
MS $ADVICE T 



A 2-byte integer. Access mode for an object. One 
of the following predefined values: 

MS_$R 
Read access. 

MS_$RX 

Read and execute access. 

MS_$WR 

Read and write access. 

MS_$WRX 

Write and execute access. 

MS_$RIW 

Read with intent to write. 

A 2-byte integer. Usage patterns for accessing a 
file. One of the following predefined values: 

MS_$NORMAL 
Normal use. 

MS_$RANDOM 
Random access use. 

MS_$SEQUENTIAL 
Sequential access use. 

Reserved for future use. 

Four bytes that are reserved for future use. 
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MS DATA TYPES 



MS $ATTRB T 



An attribute record. The diagram below illustrates 
the MS_$ATTRIB_T data type: 



time_$clockh_t 
time_$clockh_t 
time $clockh t 



byte: 
offset 




1 

2 

6 

10 

14 

18 



integer 



integer 



integer 



integer 



integer 



field name 

permanent 
immutable 
curjen 

blocks_used 

dtu 

dtm 

dtcr 



o 



permanent 

A boolean value that indicates whether the 

object is permanent (TRUE) or temporary 

(FALSE) 

immutable 

A boolean value that indicates whether the 
object can be modified. The value TRUE means 
that the object is immutable. The value FALSE 
means that the object is not immutable and can 
therefore be modified. 

cur_len 

Current length, in bytes, of the object. 

blocks _ used 

The number of blocks used for the object. 

dtu 

Date-time used, in TME_$CLOCKH_T 

format. 

dtm 

Date-time modified, in TME_$CLOCKH_T 

format. 

dtcr 

Date- time created, in TME_$CLOCKH_T 

format. 
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MS DATA TYPES 



MS $CONC MODE T 



A 2-byte integer. Concurrency mode for an object. 
One of the following predefined values: 

MS_$NR_X0R_1W 

Allows one writer or any number of readers. 



MS $PERM OPT T 



MS _$CO WRITERS 

Allows any number of readers and/or writers. 

A 2-byte integer. Available options for 

MS _$MK_ PERMANENT. One of the following 

predefined values: 



STATUS $T 



MS_$MK_BAK 

Makes a backup copy of file. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 ■ 

23). 
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XOID $T 



code 

A signed number that identifies the type of error 

that occurred (bits - 15). 

Unique identifier of an object. Used by type 
managers only. The diagram below illustrates the 
XOID_$T datatype: 



predefined 
type 



uid $t 



byte: 
offset 



0: 

4: 

8: 

12: 



31 



integer 



integer 



integer 



integer 



field name 

rful 
rfu2 
UID 



> 



Field Description: 

rful 

Reserved for future use. 

rfu2 

Reserved for future use. 



UID 

Unique identifier for an object. 
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MS_$ADDMAP 

MS_$ADDMAP 

Adds a new map of a different portion of previously mapped object. 

FORMAT 

address = MS_$ADDMAP (old-address, start, desired-length, 

mapped-length, status) 

RETURN VALUE 

address 

Pointer to the first byte of additional mapped portion, in UNIV_PTR format. This is a 
4- byte integer. 

INPUT PARAMETERS 

old- address 

Pointer to the first byte of the currently mapped portion of the object, in UNIV_PTR 
format. This is a 4-byte integer. Use the pointer returned by the most recent call to 
MS_$MAPL, MS_$CRMAPL, or MS_$REMAP. 

start 

First byte to be mapped. This is a 4-byte integer. 

desired- length f~~ 

Number of bytes to map. This is a 4-byte integer. V 

OUTPUT PARAMETERS 

mapped- length 

Number of bytes mapped. This is a 4-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 

Data Types section for more information. Possible values are: v - 

STATUS_$OK Completed successfully. 

MS_$NOT_MAPPED 

No object is mapped at the given virtual address. 

MS _ $BAD _ LENGTH 

Desired-length is invalid. 
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MS $ADDMAP 



USAGE 



This call maps a different portion of a previously mapped object. It is unlike 
MS_$REMAP in that it does not move the existing window to the object but adds a new 
window at a different address from the original mapping. The new window is not 
contiguous with the old window. 

When you add a new map of a file, certain attributes of the mapping (extend, access, 
concurrency) are left the same as in the original mapping. If you used MS _ $ADVICE to 
provide file access advice, the advice in effect for the first part of the currently mapped 
section is propagated to the newly mapped section. Also, MS_$ADDMAP does not change 
the lock mode of the object. 

The locking mode is maintained on the previously mapped object. If you try to unmap the 
previous window and the object is temporary, you will get an "object not found" error 
message; if the object is permanent, you will run into concurrency problems because the 
object will become unlocked. You should unmap the second window before attempting to 
unmap the previous window. 
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MS _$ ADVICE 

MS_$ADVICE 

Provides the operating system with information on how you plan to access an object. This 
information helps the system optimize performance when managing the object. 

FORMAT 

MS_$ADVICE (address, length, access, options, record-length, status) 

INPUT PARAMETERS 

address 

Pointer to the first byte to provide advice for, UNIV_PTR format. This is a 4-byte 
integer. Use the pointer returned by the most recent call to MS_$CRMAPL, 
MS _ $MAPL, or MS _ $REMAP. 

length 

Number of bytes to provide advice for. This is a 4-byte integer. 

access 

Method of accessing the object, in MS_$ACCESS_T format. Specify only one of the 
following predefined values: 

MS_$NORMAL You do not have a predicted manner for accessing the object. This is the 
default if a program never uses MS _$ AD VICE. 

MS_$RANDOM You access the object randomly. 

MS_$SEQUENTIAL 

You access the object sequentially. 

options 

Reserved for future use, in MS_$ADVICE_T format. This is a 4-byte integer. In Pascal, 
specify this parameter using the empty set []. In C and FORTRAN, declare a variable and 
initialize it to 0. 

record- length 

Number of bytes in a record in the mapped object. This is a 4-byte integer. If you do not 
know the record length, or if the object is not record-structured, specify 0. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. 

USAGE 

MS_$ADVICE provides the operating system with information on how you plan to access 
an object. When you work with a mapped object, the system brings pages into memory as 
needed. By using MS_$ADVICE, you can change the number of pages that the system 
gets when a page fault occurs. This helps the system provide better performance when 
managing the object on your behalf. 

MS MS- 8 
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MS _$ AD VICE 

Although it is not required that you use MS _ $ADVICE, you should use it whenever you 
have a predicted type of file access. In addition, you can use MS_$ADVTCE more than 
once to change the advice for a mapped object. 

If you remap an object with MS_$REMAP, the advice in effect for the first part of the 
currently mapped section is propagated to the newly mapped section. 
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MS $ATTRIBUTES 



MS $ATTRffiUTES 



/ 



Returns the selected attributes of a mapped object. V. 

FORMAT 

MS_$ ATTRIBUTES (address, attrib-buf, attrib-len, attrib-max, status) 

INPUT PARAMETERS 

address 

Pointer to the first byte of the currently mapped portion of the object, in UNIV_PTR 
format. This is a 4-byte integer. Use the pointer returned by the most recent call to 
MS_$MAPL, MS_$CRMAPL, or MS_$REMAP. 

OUTPUT PARAMETERS ( 

attrib-buf 

Buffer in which to receive the attributes, in MS_$ATTRIB_T format. This data type is 
22 bytes long. See the MS Data Types section for more information. 

attrib-len 

Length of the attributes returned in the attributes buffer. This is a 2-byte integer. 



INPUT PARAMETERS 

attrib-max 

Length of the attributes buffer. This is a 2-byte integer. Specify the length of the 
attributes buffer in the attrib__buf parameter. This value defines the maximum amount 
of information that MS $ATTRIBUTES can return. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. 

USAGE 

Use MS _ $ATTRBBUTES to get information about selected attributes of a mapped object. 
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MS_$CRMAPL 

MS_$CRMAPL 
) Creates, maps, and locks an object. 

FORMAT 

address = MS_$CRMAPL (name, name-length, start, desired-length, 

concurrency, status) 

RETURN VALUE 

address 

Pointer to the first mapped byte of the object, in UNIV_PTR format. This is a 4-byte 
integer. 

The first mapped byte is not necessarily the first byte of the object; it is the byte you 
specify in the start parameter. 

' INPUT PARAMETERS 

name 

Pathname of the object to be mapped, in NAME_$PNAME_T format. This is an array 
of up to 256 characters. 

name- length 

Length of the pathname. This is a 2-byte integer. 

start 

First byte to be mapped. This is a 4-byte positive integer. To specify the first byte in an 
object, provide a start value of 0. 

desired- length 

Number of bytes to map, including the start byte. This is a 4-byte positive integer. 

concurrency 

Concurrency mode for the object, in MS_$CONC_MODE_T format. This is a 2-byte 
integer. Specify only one of the following predefined values: 

MS_$NR_X0R_1W 

Allows one writer or any number of readers. 

MS_$COWRITERS 

Allows any number of readers and/or writers. 
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MS_$CRMAPL 

OUTPUT PARAMETERS ^ 

...... 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. Possible values are: 

STATUS _$OK Object created. 

MS _ $BAD _ ACCESS Illegal concurrency value. 

MS_$IN_USE Object is currently locked. 

MS _$NO_ SPACE Insufficient virtual address space to map. 

NAME_$ALREADY_EXISTS Name given already exists. 

Other naming server errors See the NAME_$ error codes. 

USAGE 

MS_$CRMAPL creates a file only if the name you specify does not already exist. The call 
implicitly uses an MS manager access mode of MS_$WR. Thus the object is always 
mapped for write access. You can get an exclusive write lock (if you specify a concurrency 
of MS_$WR_XOR_lW) or you can get a shared write lock (if you specify a concurrency 
of MS_$COWRITERS.) See the description of MS_$MAPL for more information on 
locks. 

MS_$CRMAPL always uses an extend value of TRUE. Thus you can extend the object to 
the length you specify in the desired-length parameter. 
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MS_$CRTEMP 
[ ) Creates, maps, and locks an object. 



FORMAT 

address = MS_$CRTEMP (volume-name, name-length, start, desired-length, 

concurrency, status) 

RETURN VALUE 

address 

Pointer to the first mapped byte of the temporary object, in UNIV_PTR format. This is a 
4-byte integer. 

The first mapped byte is not necessarily the first byte of the object; it is the byte you 
specify in the start parameter. 

INPUT PARAMETERS 

vol- name 

Pathname of the volume where the object is to be mapped, in NAME_$PNAME_T 
format. This is an array of up to 256 characters. 

name-length 

Length of the pathname. This is a 2-byte integer. 

start 

First byte to be mapped. This is a 4-byte positive integer. To specify the first byte in an 
object, provide a start value of 0. 

desired- length 

Number of bytes to map, including the start byte. This is a 4-byte positive integer. 

concurrency 

Concurrency mode for the object, in MS_$CONC_MODE_T format. This is a 2-byte 
integer. Specify only one of the following predefined values: 

MS_$NR_X0R_1W 

Allows one writer or any number of readers. 

MS_$COWRITERS 

Allows any number of readers and/or writers. 
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MS_$CRTEMP 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. Possible values are: 

STATUS _$OK Object created. 

MS _$BAD_ ACCESS Illegal concurrency value. 

MS_$IN_USE Object is currently locked. 

MS _$NO_ SPACE Insufficient virtual address space to map. 

Other naming server errors See the NAME_$ error codes. 

USAGE 

MS_$CRTEMP creates a temporary file that will reside on the volume you specify and 
returns the mapped address. The call implicitly uses an MS manager access mode of 
MS_$WR. Thus the object is always mapped for write access. You can get an exclusive 
write lock (if you specify a concurrency of MS_$WR_XOR_lW) or you can get a shared 
write lock (if you specify a concurrency of MS_$COWRITERS.) See the description of 
MS_$MAPL for more information on locks. 

MS_$CRTEMP always uses an extend value of TRUE. Thus you can extend the object to 
the length you specify in the desired-length parameter. 

Temporary files are unlike permanent files in that they do not have pathnames. Also, they 
disappear when you shut down the system or call MS_$UNMAP. To make a temporary 
file permanent, you should use MS _$MK_ PERMANENT. 
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MS_$FW_FILE 

Forces the system to write a mapped file onto disk. 

FORMAT 

MS $FW FILE (address, status) 



INPUT PARAMETERS 

address 

Pointer to the first byte of the currently mapped portion of the object, in UNIV_PTR 
format. This is a 4-byte integer. Use the pointer returned by the most recent call to 
MS_$MAPL, MS_$CRMAPL, or MS_$REMAP. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. 

USAGE 

When you work with mapped objects, the system uses a predefined set of conditions to 
determine when to write information (stored in memory) onto the disk. However, if you 
need to supplement the system's actions, you can use MS_$FW_FILE to force the system 
to write an object onto disk. 

When you use MS_$FW_FILE, the system force writes the entire object, even if the 
currently mapped portion does not begin at byte 0. However, the system writes only the 
changed portions of the object onto the disk. 

When you force-write a permanent object, the system also force-writes the directory where 
the object is cataloged. 
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MS_$FW_PARTIAL 

MS _ $FW _ PARTIAL 

Forces the system to write a portion of a mapped file onto disk. ^ 

FORMAT 

MS_$FW_FILE (address, deired-length. status) 

INPUT PARAMETERS 

address 

Pointer to the first byte of the currently mapped portion of the object, in UNIV_PTR 
format. This is a 4-byte integer. Use the pointer returned by the most recent call to 
MS_$MAPL, MS_$CRMAPL, or MS_$REMAP. 

desired- length 

Number of bytes to force write, including the start byte. This is a 4-byte positive integer. [ 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. 



USAGE 



\ 



When you work with mapped objects, the system uses a predefined set of conditions to 
determine when to write information (stored in memory) onto the disk. However, if you 
need to supplement the system's actions, you can use MS _$FW_ PARTIAL to force the 
system to write part of an object onto disk. This call is useful if you do not wish to write 
out the entire database to disk but just a specified portion. If you wish to force write the 
entire object, use MS_$FW_FILE. 
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MS_$MAPL 

, J Maps the specified portion of a file-system object into an available region of the process 

address space. This call also locks the object. 

FORMAT 

address = MS_$MAPL (name, name-length, start, desired-length, concurrency, 
access, extend, length-mapped, status) 

RETURN VALUE 

address 

Pointer to the first mapped byte of the object, in UNIV_PTR format. This is a 4-byte 
integer. 



o 



r 



The first mapped byte is not necessarily the first byte of the object; it is the byte you 
specify in the start parameter. 

INPUT PARAMETERS 

name 

Pathname of the object to be mapped, in NAME_$PNAME_T format. This is an array 
of up to 256 characters. 

name- length 

Length of the pathname. This is a 2-byte integer. 

start 

First byte to be mapped. This is a 4-byte positive integer. To specify the first byte of an 
object, provide a start value of 0. 

desired- length 

Number of bytes to map, including the start byte. This is a 4-byte positive integer. 

concurrency 

Concurrency mode for the object, in MS_$CONC_MODE_T format. This is a 2-byte 
integer. Specify only one of the following predefined values: 

MS_$NR_X0R_1W 

Allows one writer or any number of readers. 

MS_$COWRITERS 

Allows any number of readers and/or writers. 
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access 

The access mode desired, in MS_$ACC_MODE_T format. This is a 2-byte integer. 
Specify only one of the following predefined values: 

MS_$R Read access. 

MS_$RX Read and execute access. 

MS_$WR Read and write access. 

MS_$WRX Write and execute access. 

MS_$RIW Read with intent to write. 

The access requested must be a subset of the access permitted by the protection for the 
object. 

extend 

A Boolean value that indicates whether the object can be extended. The value TRUE 
indicates that the length given in the desired-length parameter should be mapped, even if 
the object is shorter. Writing beyond the end of the object, but within the space mapped, 
extends the object. FALSE indicates that the amount mapped should be no greater than 
the actual length of the file. 

OUTPUT PARAMETERS 

length-mapped 

Number of bytes actually mapped. This is a 4-byte positive integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. Possible values are: 

STATUS _$OK Object created. 

MS _$BAD_ ACCESS 

Access type is illegal. 

MS _ $IN _ USE Ob j ect could not be locked . 

NAME_$NOT_FOUND 

No object exists with the given name. 

Other naming-server errors 

See the NAME_$ error codes. 

USAGE 

Use MS_$MAPL to map files that contain data in a user-defined format. For example, 
font files are a case where MS_$MAPL is appropriate. Do not use MS_$MAPL to access 
DOMAIN record structured files; use STREAM_$ calls to access these files. 
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/ N 



MS_$MAPL locks a file, in addition to mapping it. The lock is determined by the 
concurrency and access modes that you specify. MS_$MAPL can obtain the following 
types of locks: 



o 



Lock 


Concurrency Mode 


Access Mode 


Protected Read 


MS_$NR_X0R_1W 


MS_$R or MS_$RX 




Protected RIW 


MS_$NR_X0R_1W 


MS_$RIW 




Shared Read 


MS_$COWRITERS 


MS_$R or MS_$RX or 


MS_$RIW 


Exclusive Write 


MS_$NR_X0R_1W 


MS_$WR or MS_$WRX 




Shared Write 


MS_$COWRITERS 


MS_$WR or MS 





Once you have locked a file, the MS manager allows other processes to map the file only if 
these processes request a lock that is compatible with your lock. The following lock 
combinations are allowed and prohibited. (Y means that the combination is allowed; N 
means that the combination is prohibited.) 



Existing Lock 


Requested Lock 




Protected 


Protected 


Shared 


Exclusive 


Shared 




Read 


RIW 


Read 


Write 


Write 


Protected Read 


Y 


Y 


Y 


N 


N 


Protected RIW 


Y 


N 


Y 


N 


N 


Shared Read 


Y 


Y 


Y 


N 


Y * 


Exclusive Write 


N 


N 


N 


N 


N 


Shared Write 


N 


N 


Y * 


N 


Y * 



* These locks are allowed only if the processes are on the same node. 



O 



MS- 19 



MS 



MS $MAPL STREAM 



MS $MAPL STREAM 



Maps the specified filesystem object, given its xoid, into an available region of the process 
address space. This call also locks the object and protects the mapping on a UNIX EXEC 
call. For type managers only. 



FORMAT 

address-ptr := MS_$MAPL_STREAM (xoid, start, desired-length, concurrency, 

access, extend, length-mapped, status) 

RETURN VALUE 

address-ptr 

Pointer to the first mapped byte of the object, in UNIV_PTR format. This is a 4-byte 
integer. 

The first mapped byte is not necessarily the first byte of the object; it is the byte you 
specify in the start parameter. 

INPUT PARAMETERS 

xoid 

Xoid, or unique identifier of an object in XOID_$T format. This data type is 16-bytes 
long. See the MS Data Types section for details. 

start 

First byte to be mapped. This is a 4-byte positive integer. To specify the first byte of an 
object, provide a start value of 0. 

desired- length 

Number of bytes to map, including the start byte. This is a 4-byte positive integer. 
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concurrency 

Concurrency mode for the object, in MS_$CONC_MODE_T format. This is a 2-byte 
integer. Specify only one of the following predefined values: 

MS_$NR_X0R_1W 

Allows one writer or any number of readers. 

MS_$COWRITERS 

Allows any number of readers and/or writers. 

access 

The access mode desired, in MS_$ACC_MODE__T format. This is a 2-byte integer. 
Specify only one of the following predefined values: 

MS_$R Read access. 

MS_$RX Read and execute access. 

MS_$WR Read and write access. 

MS_$WRX Write and execute access. 

MS_$RIW Read with intent to write. 

The access requested must be a subset of the access permitted by the protection for the 
object. 

extend 

A Boolean value that indicates whether the object can be extended. The value TRUE 
indicates that the length given in the desired-length parameter should be mapped, even if 
the object is shorter. Writing beyond the end of the object, but within the space mapped, 
extends the object. FALSE indicates that the amount mapped should be no greater than 
the actual length of the file. 

OUTPUT PARAMETERS 

length-mapped 

Number of bytes actually mapped. This is a 4-byte positive integer. 
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status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. Possible values are: 

STATUS _$OK Object created. 

MS _$BAD_ ACCESS 

Access type is illegal. 

MS_$IN_USE Object could not be locked. 



V. 



USAGE 



Use MS _$MAPL_ STREAM to map objects that you access through a type manager. 
Note that you use MS _ $MAPL _ STREAM only through a type manager. For details, see 
the Extending the DOMAIN Streams Facility manual. 

MS _$MAPL_ STREAM protects the mapping on a UNIX EXEC call. Conversely, with 
MS_$MAPL, the UNIX EXEC call unmaps any objects on any open streams. 

MS _$MAPL_ STREAM also locks the object. The lock is determined by the concurrency 
and access modes that you specify. MS _$MAPL_ STREAM can obtain the following types 
of locks: 



Lock 


Concurrency Mode 


Access Mode 


Protected Read 


MS_$NR_X0R_1W 


MS_$R or MS_$RX 




Protected RIW 


MS_$NR_X0R_1W 


MS_$RIW 




Shared Read 


MS_$CQWRITERS 


MS_$R or MS_$RX or 


MS_$RIW 


Exclusive Write 


MS_$NR_X0R_1W 


MS_$WR or MS_$WRX 




Shared Write 


MS_$COWRITERS 


MS_$WR or MS 
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Once you have locked an object, the MS manager allows other processes to map the object 
only if these processes request a lock that is compatible with your lock. The following lock 
combinations are allowed and prohibited. (Y means that the combination is allowed; N 
means that the combination is prohibited.) 



Existing Lock 


Requested Lock 




Protected 


Protected 


Shared 


Exclusive 


Shared 




Read 


RIW 


Read 


Write 


Write 


Protected Read 


Y 


Y 


Y 


N 


N 


Protected RIW 


Y 


N 


Y 


N 


N 


Shared Read 


Y 


Y 


Y 


N 


Y * 


Exclusive Write 


N 


N 


N 


N 


N 


Shared Write 


N 


N 


Y * 


N 


Y * 



* These locks are allowed only if the processes are on the same node. 
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MS _ $MK_PERMANENT 

MS _ $MK _ PERMANENT 

Makes a temporary file permanent and names it. 

FORMAT 

MS_$MK_PERMANENT (address, option, name, name-length, status) 

INPUT PARAMETERS 

address 

Pointer to the first byte of the currently mapped portion of the temporary object, in 
UNIV_PTR format. This is a 4-byte integer. Use the pointer returned by the most recent 
call to MS _ $CRTEMP or MS _ $CRMAPL. 

option 

The attribute that is to be set, in MS_$PERM_OPT_T format. This is a 2-byte integer. 
Specify only one of the following predefined values: 

MS_$MK_BAKMake a backup (".bak") file. 

name 

Pathname of the object to be made permanent, in NAME_$PNAME_T format. This is 
an array of up to 256 characters. 

The pathname you specify must be on the same volume you used when creating the f 

temporary file. v_ 

name- length 

Length of the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status /"~^ 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS V 

Data Types section for more information. 

USAGE 

MS _$MK_ PERMANENT takes the address of a temporary object you supply from 
MS_$CRMAPL or MS_$CRTEMP and makes the file permanent. The file is also given 
the name you specify and the name is catalogued. 
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_^ MS $MK TEMPORARY 

V J Makes a permanent object temporary. 

FORMAT 

MS_$MK_TEMPORARY (address, status) 

INPUT PARAMETERS 

address 

Pointer to the first byte of the currently mapped portion of the permanent object, in 
UNIV_PTR format. This is a 4-byte integer. Use the pointer returned by the most recent 
call to MS_$MAPL, MS_$CRMAPL, or MS_$REMAP. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. 

USAGE 

MS _$MK_ TEMPORARY makes a permanent object temporary by uncataloguing its 
name. After this routine is called, the object no longer has a pathname, which means that 
the object will disappear if you call MS_$UNMAP or shut down the system. 
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MS_$NEIGHBORS s~ 

Indicates whether two temporary objects are neighbors. ^- 

FORMAT 

same-volume = MS_$NEIGHBORS (address 1, address2, status) 

RETURN VALUE 

s ame- volume 

A boolean that indicates whether two temporary objects reside on the same volume. TRUE 
means that they do. 

INPUT PARAMETERS 

addressl > 

Pointer to the first byte of the first temporary object, in UNTV_PTR format. This is a V. 

4-byte integer. Use the pointer returned by the most recent call to MS _ $CRTEMP or 
MS_$CRMAPL. 

address2 

Pointer to the first byte of the second temporary object, in UNIV_PTR format. This is a 
4-byte integer. Use the pointer returned by the most recent call to MS_$CRTEMP or 
MS_$CRMAPL. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. 

USAGE 

MS _ $NEIGHBORS allows you to determine whether two temporary mapped objects reside V v 

on the same volume. You supply the addresses of the objects from previous mappings. 
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MS_$RELOCK 

Changes the lock on an object. 

FORMAT 

MS_$RELOCK (virtual-address, access, status) 

INPUT PARAMETERS 

virtual- address 

Pointer to the first mapped byte of the object whose lock you want to change, in 
UNIV_PTR format. This is a 4-byte integer. Use the pointer returned by an earlier call 
to MS _ $MAPL, MS _ $CRMAPL, or MS _ $REMAP . 

access 

New access mode, in MS_$ACC_MODE_T format. This is a 2-byte integer. Specify 
only one of the following predefined values: 

MS_$R Read access. 

MS_$RX Read and execute access. 

MS_$WR Read and write access. 

MS_$WRX Read, write, and execute access. 

MS_$RIW Read with intent to write. 

If you specify an access mode of MS_$RIW when you first lock an object, you cannot 
relock the object with MS_$R access. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. Possible values are: 

STATUS _$OK Completed successfully. 

MS_$NOT_MAPPED No object is mapped at the supplied virtual address. 

MS _$BAD_ ACCESS Access mode given is incorrect. 

FILE _ $ILLEGAL _ LOCK _ RQST 

Illegal lock request (file server); the access mode given is 
incorrect. 

USAGE 

MS_$RELOCK changes the lock on an object. With MS_$RELOCK, you specify a new 
access type. This new access, in combination with the current concurrency mode, forms a 
new lock. You can relock a file in the following ways: 
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Current Lock 


Changes 


Protected read 


Change to exclusive write by specifying 




the access mode MS_$WR or MS_$WRX. 




Change to protected RIW by specifying 




the access mode MS_$RIW. 


Protected RIW 


Change to exclusive write by specifying 




the access mode MS_$WR or MS_$WRX. 




Cannot change to protected read by 




specifying the access mode MS_$R. 


Shared read 


Change to shared write by specifying 




the access mode MS_$WR or MS_$WRX. 


Exclusive write 


Change to protected read by specifying 




the access mode MS_$R. 




Change to protected RIW by specifying 




the access mode MS_$RIW. 


Shared write 


Change to shared read by specifying 




MS_$R or MS_$RIW. 



See the description of MS _ $MAPL for a list of the concurrency/access combinations for 
each lock. 
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MS_$REMAP 

Maps a different portion of a previously mapped object. 

FORMAT 

address = MS_$REMAP (old-address, start, desired-length, 

remapped-length, status) 

RETURN VALUE 

address 

Pointer to the first byte of the new mapped section, in UNIV_PTR format. This is a 
4-byte integer. 

INPUT PARAMETERS 

old- address 

Pointer to the first byte of the currently mapped portion of the object, in UNIV_PTR 
format. This is a 4-byte integer. Use the pointer returned by the most recent call to 
MS_$MAPL, MS_$CRMAPL, or MS_$REMAP. 

start 

First byte to be mapped. This is a 4-byte integer. 

desired- length 

Number of bytes to remap. This is a 4-byte integer. 

OUTPUT PARAMETERS 

remapped- length 

Number of bytes remapped. This is a 4-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. Possible values are: 

STATUS _$OK Completed successfully. 

MS _ $NOT _MAPPED 

No object is mapped at the given virtual address. 

MS _ $BAD _ LENGTH 

Desired-length is invalid. 
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USAGE 



This call maps a different portion of an already mapped object and unmaps the previously 
mapped portion. This call is useful for moving a sliding window over a big file. 

When you remap a file, certain attributes of the mapping (extend, access, concurrency) are 
left the same as in the original mapping. If you used MS_$ADVICE to provide file access 
advice, the advice in effect for the first part of the currently mapped section is propagated 
to the newly mapped section. Also, MS_$REMAP does not change the lock mode of the 
object. 
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MS_$TRUNCATE 



Truncates a mapped object to the specified length. 

FORMAT 

MS_$TRUNCATE (address, length, status) 

INPUT PARAMETERS 

address 

Pointer to the first byte of the currently mapped portion of the object, in UNIV_PTR 
format. This is a 4-byte integer. Use the pointer returned by the most recent call to 
MS_$MAPL, MS_$CRMAPL, or MS_$REMAP. 

length 

Number of bytes to keep in the mapped object, starting at the first byte in the object. This 
is a 4-byte integer. Everything after this length is truncated. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. 

USAGE 

MS_$TRUNCATE shortens a mapped file to the length that you specify. In addition, you 
can use MS _ $TRUNCATE to define a length for a file, even if you are not throwing away 
data. For example, when you unmap a file, the system may set the file length to a 
page-aligned value. (That is, the length will be a multiple of 1024.) However, you can use 
MS_$TRUNOATE to shorten the file to a nonpage-aligned value. 

For example, if a file contains only 20 bytes of data, you can use MS _ $TRUNCATE to set 
the file length to 20. When you unmap the file, the length will be 20 rather than 1024. Use 
MS _ $ATTRD3UTES to determine the current file length and number of blocks used. 
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MS_$UNMAP ^ 
Unmaps a previously mapped object. v 

FORMAT 

MS_$UNMAP (address, length, status) 

INPUT PARAMETERS 

address 

Pointer to the first byte of the currently mapped portion of the object, in UNIV_PTR 
format. This is a 4-byte integer. Use the pointer returned by the most recent call to 
MS_$MAPL, MS_$CRMAPL, or MS_$REMAP. 

length 

Number of mapped bytes. This is a 4-byte integer. Use the length you requested in the 

most recent call to MS _ $MAPL, MS _ $CRMAPL, or MS _ $REMAP. (~~*\ 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MS 
Data Types section for more information. Possible values are: 

STATUS _$OK Completed successfully. 

MS_$NOT_MAPPED V- 

Address and length given do not refer to an object mapped with 
MS_$MAPL. 

USAGE 

MS_$UNMAP unmaps and unlocks an object mapped and locked with MS_$MAPL or 
MS_$CRMAPL. You cannot unmap a subset of the object. s"~^. 

If the original object is on a remote node, changes made in the mapped version are written 
back to the original object when MS_$UNMAP is executed. If the original object is on the 
local node, changes made in the mapped version of the object will be written back to the 
original object when the space they occupy in memory is needed. 

If the object was mapped with the extend parameter equal to TRUE, and your program 
modified part of the extension space, the original object is extended to include those 
modifications. Parts of the extension space beyond the last modification are not added to 
the original object. 

An object locked by several calls to MS_$MAPL by different processes will remain locked 
until all the processes have unmapped the object. 
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ERRORS 

MS _$BAD_ ACCESS 

Unsupported access rights requested. 

MS _ $BAD _LENGTH 
Bad length. 

MS_$IN_USE 

Object is locked by another process or in an incompatible mode. 

MS _ $INSUFFICIENT _ RIGHTS 

You have some access rights to the object, but not the ones you requested. 

NAME_$NAME_NOT_FOUND 

No object exists with the given name. 

MS_$NO_RIGHTS 

You do not have any access rights to the object. 

MS _$NO_ SPACE 

No space. 

MS _ $NOT _MAPPED 

No object mapped at the virtual address supplied. 

MS_$OBJECT_NOT_FOUND 

The object does not exist, or it is not accessible over the network. 

MS _ $WRONG _ LEVEL 

Attempt to release segment mapped by previous level. 

STATUS _$OK 

Successful completion. 

Other naming server errors. 

See the NAME $ error codes. 
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MTS 



The MTS (Streams-Magtape) programming calls perform streams operations to magnetic tape 
devices. This section describes their data types, call syntax, and error codes. Refer to the 
Introduction at the beginning of this manual for a description of data-type diagrams and call 
syntax format. 
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MTS-1 MTS 



MTS DATA TYPES 



CONSTANTS 

MTS _ $CURRENT_FILE_ SEQ 

MTS_$END_FILE_SEQ 

MTS_$FERST_A 

MTS $LAST A 



File sequence number for current file. 

File sequence number for last tape file. 

MTS_$UNIT_A 

First attribute in MTS_$ATTR_T. 

MTS _ $BUFFER _ OFFSET _ A 

Last attribute in MTS $ATTR T. 



DATA TYPES 



MTS $ATTR T 



A 2-byte integer. THE User-modifiable tape file 
attributes. One of the following predefined values: 

MTS_$UNIT_A 
Tape unit number. 

MTS _ $LABELED _ A 
Labeled volume. 

MTS_$REOPEN_VOL_A 
Reopen volume. 

MTS_$CLOSE_VOL_A 
Close file and volume. 

MTS_$SAVE_VOL_POS_A 
Save position on close. 

MTS_$VOL_DEVICE_A 
Device type. 

MTS_$VOL_ID_A 
Volume ID. 

MTS _ $VOL_ ACCESS _ A 
Volume accessibility. 

MTS_$OWNER_ID_A 
Owner ID. 

MTS_$FILE_SEQUENCE_A 
File sequence number. 

MTS_$RECORD_FORMAT_A 
Record format. 

MTS_$BLOCK_LENGTH_A 
Block length. 
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MTS _ $RECORD _LENGTH_ A 
Maximum record length. 

MTS_$ASCII_NL_A 
ASCII newline head-length 

MTS _ $FILE_ SECTION_ A 
File section number. 

MTS_$FILE_ID_A 
File ID. 

MTS_$FILE_SET_ID_A 
File set ID. 



MTS_$GENERATION_A 
Generation number. 

MTS _ $GENERATION_ VERSION_ A 
Generation version number. 



O 



MTS _ $CREATE_DATE_ A 
Creation date. 



o 



MTS_$EXP_DATE_A 
Expiration date. 

MTS_$FILE_ACCESS_A 
File accessibility. 



MTS _ $SYSTEM_ CODE_ A 
System code. 

MTS_$SYSTEM_USE_A 
System use. 



MTS $ATTR VALUE T 



MTS _ $BUFFER_ OFFSET_ A 
Buffer offset. 

Attribute values. The diagram below illustrates the 
MTS _$ATTR_ VALUE _T data type: 



MTS- 3 



MTS 



MTS DATA TYPES 



predefined 
type 



byte: 
offset 



0: 



0: 



n: 



31 



7 



boolean 



char 



* * 



char 



integer 



or 



or 



field name 



Field Description: 



An integer value. 



v ' 



MTS $DEVICE T 



A Boolean value. 



A character string. 

A 2-byte integer. Type of device. One of the 
following predefined values: 

MTS_$MT 
Magtape device. 



V_- 



MTS_$HANDLE_T 
MTS $RW T 



STATUS $T 



MTS_$NOT_REALLY 
Not currently supported. 

MTS_$CT 

Cartridge tape device. 

A 4-byte integer. A handle to a tape descriptor file. 

A 2-byte integer. Read or write status. One of the 
following predefined values: 

MTS_$READ 
Read operation. 

MTS _$ WRITE 
Write operation. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 
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byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


] 31 


or 





fail 




- 


24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



o 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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Table MTS-1. Magnetic Tape Volume and File Attributes 



Mnemonic 


Type 


Default 


Definition 


MTS_$UNIT_A 


int 





magtape unit number 
(normally 0) 


MTS_$LABELED_A 


t/f 


true 


true = ANSI labeled volume 
false = unlabeled volume 


MTS_$REOPEN_VOL_A 


t/f 


false 


true = reopen previously used 
volume (suppresses 
rewind) 

false = do not reopen 


MTS_$CLOSE_VOL_A 


t/f 


true 


true = volume closed when file 

is closed 
false = leave volume open 


MTS_$SAVE_VOL_POS_A 


t/f 


false 


true = saves volume position 
when volume is closed 
(for reopen) 

false = rewind volume when 
closed 


MTS_$VOL_DEVICE A 


int 





type of device: 

tfp_$mt=0 for magtape 
tfp_$ct=3 for cartridge 


MTS_$VOL_ID_A 


char 


-auto 


volume identifier (labeled 
volumes) (Automatically 
generated.) Six-character 
string maximum. 


MTS_$VOL_ACCESS_A 


char 


■i ii 


volume accessibility (labeled 
volumes only) . The default 
is the space character. 


MTS_$VOL_OWNER_ID_A 


char 


-auto 


volume owner (labeled volumes) 
Maximum string length is 14. 


MTS_$FILE_SEQUENCE A 


int 


1 


file sequence number. Possible 




"cur" 




values are an integer, "cur" for 




"end" 




current file, "end" for new file 
at end of labeled volume. 


MTS_$RECORD_FORMAT A 


char 


D 


record format. Possible values: 
"F" = fixed length 
"D" = variable length 
"S" = spanned 
"U" = undefined 


MTS_$BLOCK_LENGTH_A 


int 


2048 


block length, in bytes 


MTS_$RECORD_LENGTH A 


int 


2048 


maximum record length, in bytes 



..y 
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Table MTS-1. Magnetic Tape Volume and File Attributes (Continued) 



o 



Mnemonic 


Type 


Default 


Definition 


MTS_$ASCII_NL_A 


t/f 


true 


true = ASCII newline handling. 
Strip newlines on write, 
supply them on read 

false = no newline handling 


MTS_$FILE_SECTION_A 


int 


1 


file section number 
(labeled volumes) 


MTS_$FILE_ID_A 


char 


ii M 


file identifier 
(labeled volumes) 


MTS_$FILE_SET_ID_A 


char 


■I ii 


file set identifier 
(labeled volumes) 


MTS_$GENERATION_A 


int 


1 


generation of file 
(labeled volumes) 


MTS_$GENERAT I ON_VERS I ON_A 


int 


1 


generation version of file 
(labeled volumes) 


MTS_$ CREATE_D ATE_A 


date 


-auto 


creation date of file 
(labeled volumes) 


MTS_$EXP_DATE_A 


date 


-auto 


expiration date of file 
(labeled volumes) 


MTS_$FILE_ACCESS_A 


char 


n M 


file accessibility 
(labeled volumes) 


MTS_$SYSTEM_CODE_A 


char 


H ii 


system code (labeled volumes) 


MTS_$SYSTEM_USE_A 


char 


ii H 


system use (labeled volumes) 


MTS_$BUFFER_OFFSET_A 


int 





buffer offset (labeled volumes) 
Must be zero. 
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MTS_$CLOSE_DESC 

MTS_$CLOSE_DESC 

Closes a magtape descriptor file. 

FORMAT 

MTS_$CLOSE_DESC (handle, update, status) 

INPUT PARAMETERS 

handle 

Pointer to the open magtape descriptor file, in MTS_$HANDLE_T format. This is a 
4-byte integer. Specify the handle returned by MTS_$OPEN_DESC, 
MTS_$COPY_DESC, or MTS_$ CREATE _DESC. 

update 

Boolean value that determines whether or not the magtape descriptor file is to be modified 
to reflect the attribute changes specified by calls to MTS_$SET_ATTR. If TRUE, the 
changes are made. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MTS 
Data Types section for more information. 

USAGE 

Programs must close magtape descriptor files before calling stream manager routines; an 
open magtape descriptor file cannot be used by the stream manager. 

Closing a magtape descriptor file invalidates its handle. 
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MTS_$COPY_DESC 

MTS_$COPY_DESC 

Copies a magtape descriptor file and opens the destination file. 

FORMAT 

handle = MTS_$COPY_DESC (src-pathname, src-namelen. dst-pathname, 

dst-namelen, status) 

RETURN VALUE 

handle 

Pointer to the open magtape descriptor file, in MTS_$HANDLE_T format. This is a 
4-byte integer. 

INPUT PARAMETERS 

src-pathname 

The pathname of the magtape descriptor file to be copied, in NAME _$P NAME __T 
format. This is an array of up to 256 characters. 

src-namelen 

Length of the source pathname, in bytes. This is a 2-byte integer. 

dst- pathname 

The pathname to which the file is to be copied, in NAME_$PNAME_T format. This is 
an array of up to 256 characters. 

The destination file must not exist before this function is called. To replace a destination 
file, call the routine NAME _$DELETE_ FILE before calling MTS_$COPY_DESC. 

dst-namelen 

Length of the destination pathname, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MTS 
Data Types section for more information. 

USAGE 

This routine copies the specified magtape descriptor file, opens the destination file and 
returns a pointer to it. 

This routine does not affect the source file. 
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MTS _ $CREATE_DEFAULT_DESC 

MTS_$CREATE_DEFAULT_DESC 

Creates a magtape descriptor file with the default volume and file attributes. \ s 

FORMAT 

handle = MTS_$CREATE_DEFAULT_DESC (pathname, namelen. status) 

RETURN VALUE 

handle 

A pointer to the open magtape descriptor file, in MTS_$HANDLE_T format. This is a 
4-byte integer. 

INPUT PARAMETERS 

pathname s 

The pathname of the descriptor file to be created, in NAME_$PNAME_T format. This > v 

is an array of up to 256 characters. 

namelen 

Length of the name, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MTS 
Data Types section for more information. 

USAGE 

This routine opens a magtape descriptor file with the default volume and file attribute 

values and returns a pointer to it. The file must not exist before this routine is called. See 

the Table in the MTS Data Types section for a list of volume and file attributes and their ^ 

defaults. ^ 
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MTS_$GET_ATTR 

MTS_$GET_ATTR 

Retrieves a given attribute from a magtape descriptor file. 

FORMAT 

MTS_$GET_ATTR (handle, attribute, value, status) 

INPUT PARAMETERS 

handle 

A pointer to the open magtape descriptor file, in MTS_$HANDLE_T format. This is a 
4-byte integer. Specify a handle returned by MTS_$OPEN_DESC, 
MTS_$COPY_DESC, or MTS_$ CREATE _DESC. 

attribute 

The attribute to be retrieved, in MTS_$ATTR_T format. This is a 2-byte integer. 
Specify only one of the following predefined values: 

mts_$unit_a mts_$labeled_a mts_$reopen_vol_a 

mts_$close_vol_a mts_$save_vol_pos_a mts_$vol_device_a 

mts_$vol_id_a mts_$vol_access_a mts_$owner_id_a 

mts_$file_sequence_a mts_$record_format_a mts_$block_length_a 

mts_$record_length_a mts_$ascii_nl_a mts_$f ile_resvl_a 

mts_$f ile_section_a mts_$f ile_id_a mts_$f ile_set_id_a 

mts_$generation_a mts_$generation_version_a mts_$create_date_a 

mts_$exp_date_a mts_$f ile_access_a mts_$system_code_a 

mts_$system_use_a mts_$buffer_off set_a 

See the Table in the MTS Data Types section for a description of volume and file attributes 
and their defaults. 

OUTPUT PARAMETERS 

value 

The current value of the specified attribute, in MTS _$ATTR_ VALUE _T format. 
Possible values are a 4-byte integer, a Boolean value, or a string, depending upon the 
attribute requested. See the Table in the MTS Data Types section for a list of volume and 
file attributes and their corresponding values. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MTS 
Data Types section for more information. 

USAGE 

Programs must call this routine once for each attribute they wish to get. 

You can change the attributes within a magtape descriptor file using the 
MTS_$SET_ATTR system call. 
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MTS_$LABEL 

MTS_$LABEL 

Labels the magtape volume described by the given magtape descriptor file. 

FORMAT 

MTS_$LABEL (pathname, namelen, status) 

INPUT PARAMETERS 

pathname 

The pathname of the magtape descriptor file, in NAME_$PNAME_T format. This is an 
array of up to 256 characters. 

The descriptor file must describe a labeled volume. 

namelen 

Length of the name, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MTS 
Data Types section for more information. 

USAGE 

MTS_$LABEL causes the volume described by the descriptor file to be labeled according 
to ANSI X3.27-1978. 

The tape volume must not be open (by previous calls to the stream manager). 
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MTS_$OPEN_DESC 

MTS_$OPEN_DESC 

Opens the specified magtape descriptor file and returns a pointer to it. 

FORMAT 

handle = MTS_$OPEN_DESC (pathname, namelen. read-write, status) 

RETURN VALUE 

handle 

A pointer to the open magtape descriptor file, in MTS_$HANDLE_T format. This is a 
4-byte integer. 

INPUT PARAMETERS 

pathname 

The pathname of the magtape descriptor file, in NAME_$PNAME_T format. This is an 
array of up to 256 characters. 

namelen 

Length of the name, in bytes. This is a 2-byte integer. 

read-write 

Read or write status, in MTS_$RW_T format. This is a 2-byte integer. Specify only one 
of the following predefined values: 

MTS_$READ Open for reading. 
MTS_$WRITE Open for writing. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MTS 
Data Types section for more information. 

USAGE 

MTS_$OPEN_DESC opens the specified magtape descriptor file for reading or writing 
and returns a pointer to it. 
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MTS_$SET_ATTR 

MTS_$SET_ATTR 

Sets an attribute within the specified magtape descriptor file. 

FORMAT 

MTS_$SET_ATTR (handle, attribute, value, status) 

INPUT PARAMETERS 

handle 

A pointer to an open magtape descriptor file, in MTS_$HANDLE_T format. This is a 
4-byte integer. Specify a handle returned by MTS _$ OPEN _DESC, 
MTS_$COPY_DESC, or MTS _$ CREATE _DESC. 

attribute 

The volume or file attribute to be set, in MTS_$ATTR_T format. This is a 2-byte 
integer. Specify only one of the following predefined values: 

mts_$unit_a mts_$labeled_a mts_$reopen_vol_a 

mts_$close_vol_a mts_$save_vol_pos_a mts_$vol_device_a 

mts_$vol_id_a mts_$vol_access_a mts_$owner_id_a 

mts_$f ile_sequence_a mts_$record_format_a mts_$block_length_a 

mts_$record_length_a mts_$ascii_nl_a mts_$f ile_resvl_a 

mts_$f ile_section_a mts_$f ile_id_a mts_$f ile_set_id_a 

mts_$generatlon_a mts_$generation_version_a mts_$create_date_a 

mts_$exp_date_a mts_$f ile_access_a mts_$system_code_a 

mts_$system_use_a mts_$buff er_offset_a 

See the Table in the MTS Data Types section for a description of volume and file attributes 
and their defaults. 

value 

The value to assign to the attribute, in MTS _$ATTR_ VALUE _T format. Possible 
values are a 4-byte integer, a Boolean value, or a string, depending upon the attribute to be 
changed. See the Table in the MTS Data Types section for a list of volume and file 
attributes and their corresponding values. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the MTS 
Data Types section for more information. 

USAGE 

Programs must call this routine once for each attribute to be set. 

You can change the attributes within -a magtape descriptor file using the Shell command 
EDMTDESC. See the DOMAIN System Command Reference for details. 
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ERRORS 

STATUS _$OK 

Successful completion. 

MTS_$BAD_BLOCK_LENGTH 
Bad block length. 

MTS _ $BAD _BUFFER_ OFFSET 
Bad buffer offset. 

MTS_$BAD_DATA 

Descriptor contains bad data. 

MTS _ $BAD _FILE _ SECTION 

Bad file section number. 

MTS _ $BAD _ FILE _ SEQUENCE 
Bad file sequence number. 

MTS _ $BAD _ GENERATION 

Bad generation number. 

MTS _ $BAD _ GENERATION _ VERSION 
Bad generation version number. 

MTS _ $BAD _RECORD _FORMAT 

Bad record format attribute. 

MTS _ $BAD _RECORD _LENGTH 
Bad record length. 

MTS_$BAD_UNIT 

Bad tape unit number. 

MTS _ $INVALID _ ATTR 

Invalid attribute to GET _ATTR/SET_ ATTR. 

MTS _ $INVALID _ DATE 

Invalid date text string. 

MTS _ $NOT _ LABELED 

Attempt to label unlabeled volume. 

MTS _ $READ _ ONLY 

SET _ ATTR on read-only file. 

MTS _ $VOL _ IN _ USE 
Volume in use. 

MTS _ $WRONG _ TYPE 

Object is not type MT_$UK>. 
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MUTEX 



The MUTEX (Mutual Exclusion) programming calls provide applications with mutual exclusion 
resource-sharing and synchronization. This section describes their data types and call syntax The 
MUTEX calls do not produce unique error messages. Refer to the Introduction at the beginning 
of this manual for a description of data-type diagrams and call syntax format. 
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MUTEX DATA TYPES 



CONSTANTS 



MUTEX $WAIT FOREVER 



integer32(-l) 

A value that tells MUTEX_$LOCK to wait forever 
without timing out. 



DATA TYPES 



MUTEX $LOCK REC T 



A mutual exclusion lock record. The diagram 
below illustrates the MUTEX_$LOCK_REC_T 
data type: 



predefined 
type 


byte: 
offset 

0: 






field name 




integer 




lock_byte 


2_$eventcount _t 


■ 


2: 

6: 


integer 


lock_ec. value 


integer 




lock_ec.awaiters 



^ — 



Field Description: 

lock _ byte 

A Boolean value that indicates whether any 

programs currently hold a MUTEX lock. 



lock_ec 

An eventcount for programs waiting for the 

MUTEX lock. The lock_ec field is in 

EC2_$EVENTCOUNT format and has two 

subfields: 



lock ec.value 



The value of the 
eventcount. 



lock_ec.awaiters Used internally by the EC2 
manager. 



MUTEX 
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MUTEX DATA TYPES 



TIME $CLOCK T 



Internal representation of time. The diagram below 
illustrates the TIME_$CLOCK_T data type: 



predefined 
record 



byte: 
offset 



field name 



o 



time_$clockh_t 


0: 
4: 


integer 




high 




integer 




low 






Field Description: 








high 








High 32 bits of the clock. 








low 








Low 16 bits of the clock. 




predefined 
record 


byte: 
offset 

0: 
2: 






field name 




positive 
integer 






high16 




positive integer 




low32 



Field Description: 

highl6 

High 16 bits of the clock. 

low32 

Low 32 bits of the clock. 
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MUTEX_$INIT 

MUTEX_$INIT 

Initializes a mutual exclusion lock record. 

FORMAT 

MUTEX_$INIT (lock-record) 

OUTPUT PARAMETERS 

lock-record 

Lock record, in MUTEX_$LOCK_REC_T format. This data type is 8 bytes long. See 
the MUTEX Data Types section for more information. 

USAGE 

Use this call to initialize a mutual exclusion (MUTEX) lock record. This lock record allows 
a program to obtain a MUTEX lock on a file. A MUTEX lock allows a program to get 
exclusive access to a shared resource. 

Initialize a MUTEX lock record within a file. First, map the file with a concurrency mode 
of MS_$COWRITERS and an access type of MS_$WR. Then use MUTEX_$INIT to 
initialize the MUTEX lock record. 
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MUTEX $LOCK 
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MUTEX_$LOCK 

Obtains a mutual exclusion lock on a file. 

FORMAT 

lock-status = MUTEX $LOCK (lock-record, wait-time) 



RETURN VALUE 

lock- status 

A Boolean value that indicates whether you obtained the lock. TRUE means that you got 
the lock; FALSE means that the call timed out before obtaining the lock. 

INPUT/OUTPUT PARAMETERS 

lock-record 

Lock record, in MUTEX_$LOCK_REC_T format. This data type is 8 bytes long. See 
the MUTEX Data Types section for more information. 



INPUT PARAMETERS 

wait- time 

The amount of time to wait for the lock, in TIME_$CLOCK_T format. This data type 
is 6 bytes long. See the MUTEX Data Types section for more information. 

If MUTEX_$LOCK cannot obtain the lock within the time you specify, the call will time 
out and return control to your program. Specify the waiting time as a relative time. Use 
the CAL routines to convert time values to TIME_$CLOCK_T format. 

If you specify the waiting time using the constant MUTEX _$WAIT_ FOREVER, the 
MUTEX_$LOCK call wait indefinitely to obtain the lock. 



USAGE 

Use MUTEX_$LOCK to obtain a mutual exclusion (MUTEX) lock on a file. A MUTEX 
lock lets you have exclusive access to a shared resource. 

MUTEX_$LOCK uses the information in a lock record to determine whether you can 
obtain the lock. (Use MUTEX_$INIT to initialize a lock record.) If another program 
already has the lock, MUTEX_$LOCK waits for the amount of time you specify. When 
MUTEX_$LOCK returns, it indicates whether you obtained the lock. 

Before calling MUTEX_$LOOK, you must map the file containing the lock record. Map 
the file with a concurrency mode of MS_$COWRITERS and an access mode of MS_$WR. 
All programs that map the same MUTEX lock record must be on the same node. 

Note that a MUTEX lock is a convention that cooperating programs use to control access to 
a resource. If a program does not use MUTEX_$LOCK and accesses the resource directly, 
you cannot guarantee mutual exclusion. 
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MUTEX_$UNLOCK 

MUTEX_$UNLOCK 

Terminates a program's mutual exclusion lock on a file. V 

FORMAT 

MUTEX $UNLOCK (lock-record) 



INPUT/OUTPUT PARAMETERS 

lock-record 

Lock record, in MUTEX_$LOCK_REC_T format. This data type is 8 bytes long. See 
the MUTEX Data Types section for more information. 



USAGE 

MUTEX_$UNLOCK terminates a program's mutual exclusion lock on a file. A waiting 
program can then obtain the lock. 
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NAME 



The NAME (Naming Server) programming calls mainpulate text-string object names and 
translate them to their system (UID) names. This section describes the data types, call syntax, 
and error codes of the NAME calls. Refer to the Introduction at the beginning of this manual for 
a description of data-type diagrams and call syntax format. 
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NAME-1 NAME 



NAME DATA TYPES 



CONSTANTS 



NAME_$COMPLEN_MAX 
NAME_$FILE 

NAME_ SLINK 

NAME $PNAMLEN MAX 



32 Maximum length of an entry name. 

1 The file type value for the enttype field of the 

DIR_ENTRY_T record. 

3 The link type value for the enttype field of the 

DIR_ENTRY_T record. 

256 Maximum length of a pathname. 



DATA TYPES 



NAME $DIR ENTRY T 



The directory entry returned by 
NAME_$READ_DIR. The diagram below 
illustrates the NAME _$DIR_ ENTRY _T data 
type: 



predefined 
type 


byte: 
offset 

0: 
2: 
4: 

36: 
40: 


15 


C 


I 


field name 




integer 




enttype 




integer 


entlen 


name $name t 


char 






entname 




% * 








integer 


unusedl 




integer 


unused2 



Field Description: 

enttype 

Type of the directory entry. Either 

NAME_$FILE or NAME_$LINK. 

entlen 

Length of the directory entry name. 

entname 

Name of the directory entry. 

unusedn 

Reserved for future use by Apollo. 
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NAME DATA TYPES 



NAME $DIR LIST T 



NAME $NAME T 



NAME SPNAME T 



STATUS $T 



A 1300-element array of 

NAME _$DIR_ ENTRY _T record structures. 

The diagram below illustrates a single element: 

An array of up to NAME_$COMPLEN_MAX 
(32) characters. 

An array of up to NAME _$PNAMLEN_ MAX 
(256) characters. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



o 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 ■ 

23). 



code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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NAME_$ADD_LINK 

NAME_$ADD_LINK 
Creates a link. 

FORMAT 

NAME_$ADD_LINK (linkname, name-length, link-text, text-length, status) 

INPUT PARAMETERS 

linkname 

Name of the link, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 

of the pathname defaults to the current working directory. If a pathname is specified 

beginning with a slash (/), the object is placed in the entry directory of the local node. ^_^^ 

name- length V — -' 

Length of the linkname, in bytes. This is a 2-byte integer. 

link-text 

Pathname to which the link refers, in NAME_$PNAME_T format. This is an array of 
up to 256 characters. 

The link text replaces the linkname when the linkname is used as part of a pathname. For 

example, suppose a link named YEATS had a link text //MAN/IN/MASK. Using the /"" N 

object name YEATS is exactly equivalent to using the pathname //MAN/IN/MASK \_ - 

directly. 

The link text must be a valid filename or pathname. It does not, however, have to refer to 
an existing object. 

text- length 

Length of the link-text pathname, in bytes. This is a 2-byte integer. 

( 
OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

A link is an object within a directory that points to another object. That is, the link is 
associated with a pathname that refers to another object. The associated pathname is 
refered to as the link text. When the link is referenced, the naming server acts as if the link 
text were given in place of the link name. 

To delete a link, you must use the naming server call NAME _$DROP_ LINK, or the Shell 
command DELETE _ LINK (DLL). 

This system call corresponds to the CRL Shell command. 
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NAME_$CNAME 

NAME_$CNAME 

Changes the last element of a pathname. 

FORMAT 

NAME_$CNAME (old-pathname, old-length, new-leaf, leaf-length, status) 

INPUT PARAMETERS 

old- pathname 

The current pathname, in NAME_$PNAME_T format. This is an array of up to 32 
characters. 

old- length 

The length of the current pathname, in bytes. This is a 2-byte integer. 

new- leaf 

The name that replaces the right-most element of the current pathname, in 
NAME_$NAME_T format. This is an array of up to 256 characters. 

leaf- length 

The length of the new-leaf name, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

NAME_$CNAME changes the right-most element of the old-pathname to the string 
specified by the new-leaf argument. 
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NAME_ $CREATE_DIRECTORY 

NAME_$CREATE_DIRECTORY 
Creates a directory. 

FORMAT 

NAME_$CREATE_DIRECTORY (directory-name, name-length, status) 

INPUT PARAMETERS 

directory- name 

Name of the directory, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 
of the pathname defaults to the current working directory. If a pathname is specified 
beginning with a slash (/), the object is placed in the entry directory of the local node. 

name- length 

Length of directory name, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

NAME _$ CREATE _ DIRECTORY creates a directory using the specified pathname and 
name length. 

This system call corresponds to the CRD Shell command. 
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NAME_ $CREATE_FILE 

NAME_ $CREATE_FILE 

Creates a permanent file. 

FORMAT 

NAME_$CREATE_FILE (filename, name-length, status) 

INPUT PARAMETERS 

filename 

Name of the file, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

name- length 

Length of the filename, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

The filename given is treated in the same way as any pathname given to the naming server. 
For example, a filename beginning with a slash (/) is placed in the entry directory of the 
local node. 
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NAME_ $DELETE_DIRECTORY 

NAME_$DELETE_DIRECTORY 
Deletes a directory. 

FORMAT 

NAME_$DELETE_DIRECTORY (directory-name, name-length, status) 

INPUT PARAMETERS 

directory- name 

Name of the directory, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 
of the pathname defaults to the current working directory. If a pathname is specified 
beginning with a slash (/), the object is placed in the entry directory of the local node. 

name- length 

Length of the name, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

NAME _$DELETE_ DIRECTORY deletes the specified directory. The directory must be 
empty for a deletion to succeed. 
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NAME_ $DELETE_FILE 

NAME _ $DELETE _ FILE 
Deletes a file. 

FORMAT 

NAME_$DELETE_FILE (filename, name-length, status) 

INPUT PARAMETERS 

filename 

Name of the file, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 
of the pathname defaults to the current working directory. If a pathname is specified 
beginning with a slash (/), the object is placed in the entry directory of the local node. 

name- length 

Length of the filename, in bytes, this is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

NAME _$DELETE_ FILE deletes the specified file. 

This system call corresponds to the DLF Shell command. 
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NAME_ $DROP _LINK 

NAME_$DROP_LINK 
Deletes a link. 

FORMAT 

NAME_$DROP_LINK (linkname, name-length, status) 

INPUT PARAMETERS 

linkname 

Name of the link, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 
of the pathname defaults to the current working directory. If a pathname is specified 
beginning with a slash (/), the object is placed in the entry directory of the local node. 

name- length 

Length of the link name, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

NAME _$DROP_ LINK deletes the specified link to an associated object. 

This system call corresponds to the DLL Shell command. 
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NAME_ $EXTRACT_DATA 

NAME_$EXTRACT_DATA 

Extracts data from a directory entry read by NAME_$READ_DIR. (Intended primarily 
for use in FORTRAN programs.) 

FORMAT 

NAME_$EXTRACT_DATA (dir-entry, entry- type, entry-length, entry-name) 

INPUT PARAMETERS 

dir-entry 

The directory entry for which you wish to extract data, in NAME_$ENTRY_T format. 
This data type is 44 bytes long. See the NAME Data Types section for more information. 

In FORTRAN programs, NAME_$READ_DIR returns the directory entries in a (22,n) 
INTEGER*2 array, where n is the maximum number of directory entries your program is 
prepared to accept. Each column in this array corresponds to an entry in the specified 
directory and contains information about that entry. 

Specify the first element of the column that corresponds to the entry for which you wish to 
extract data. 



OUTPUT PARAMETERS 

entry- type 

Object type of the entry. This is a 2-byte integer with one of the following predefined 
values: 

1 - NAME_$FILE 

the object is a file. A "file" can be either a streams file or a directory. 

2-NAME_$LINK 

the object is a link. 

entry- length 

Length of the object's name, in bytes. This is a 2-byte integer. 

entry-name 

The entry name, in NAME_$NAME_T format. This is an array of up to 32 characters. 

USAGE 

This call extracts the description of a single directory entry from the directory entry array 
(the dir-list parameter) returned by NAME_$READ_DIR. It is intended primarily for use 
in FORTRAN programs. 

In FORTRAN programs, NAME_$READ_DIR returns the directory entries in a (22,n) 
INTEGER*2 array, where n is the maximum number of directory entries your program is 
prepared to accept. Each column in this array corresponds to an entry in the specified 
directory and contains information about that entry. 

The dir-entry parameter for NAME _$EXTRACT_ DATA should be one of the array 
columns. To reference a single column, give the first element of that column. 
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NAME_$GET_NDIR 

NAME $GET NDIR 

- - / 

Returns the full pathname of the naming directory. \._ 

FORMAT 

NAME_$GET_NDIR (name, name-length, status) 

OUTPUT PARAMETERS 

name 

Pathname of the naming directory, in NAME_$PNAME_T format. This is an array of 
up to 256 characters. 

name- length 

Length of the name, in bytes. This is a 2-byte integer. 

status /" 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME V 

Data Types section for more information. 

USAGE 

The naming directory is set through the NAME _$SET_ NDIR call or the "ND 
directory-name" Shell command. This system call corresponds to the ND Shell command. 



L 
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NAME_$GET_PATH 

NAME _ $GET _ PATH 

Converts a partial pathname into a full pathname. 

FORMAT 

NAME_$GET_PATH (in-name, in-len, out-name, out-len, status) 

INPUT PARAMETERS 

in-name 

The relative pathname of an object, in NAME_$PNAME_T format. This is an array of 
up to 256 characters. 

in-len 

Length of the relative pathname, in bytes: This is a 2-byte integer. 

OUTPUT PARAMETERS 

out- name 

The full (absolute) pathname of the object, in NAME_$PNAME_T format. This is an 
array of up to 256 characters. 

out-len 

Length of the relative pathname, in bytes. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

NAME _$GET_ PATH converts a partial pathname into a full pathname. For example, if 
you have been using file F00, you can call NAME _$ GET _ PATH to find out that the full 
pathname of FOO is //FLYNN/PHL/FOO. 
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NAME_$GET_WDIR 

NAME_$GET_WDIR 

Returns the full pathname of the working directory. 

FORMAT 

NAME_$GET_WDIR (name, name-length, status) 

OUTPUT PARAMETERS 

name 

Pathname of the working directory, in NAME_$PNAME_T format. This is an array of 
up to 256 characters. 

name- length 

Length of the name, in bytes. This is a 2-byte integer. 

status f > 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME v_> 

Data Types section for more information. 

USAGE 

The working directory is set through the NAME_$SET_WDIR call or the "WD 
directory-name" Shell command. 
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NAME $READ DIR 
V J Reads a directory. 



o 



o 



FORMAT 

NAME_$READ_DIR (dir-name, name-length, dir-list, index, max-count, 
read-count, status) 

INPUT PARAMETERS 

dir-name 

Name of the directory, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 
of the pathname defaults to the current working directory. If a pathname is specified 
beginning with a slash (/), the entry directory of the local node is searched for the 
directory. 

Specifying a null character (") defaults to the current working directory. 

name- length 

Length of the name, in bytes. This is a 2-byte integer. 

If you specify a null character for the directory name, specify zero as the length. 

OUTPUT PARAMETERS 

dir-list 

A list of directory entries, in NAME _$DIR_ LIST _T format. This is an array of 
NAME_$DIR_ENTRY_T data types. See the NAME Data Types section for more 
information. 

The number of NAME _$DIR_ ENTRY _T data types in the array must equal or exceed 
max-count. 



INPUT/OUTPUT PARAMETERS 

index 

Key indicating the directory entry at which NAME _$READ_ DIR begins reading. This is 
a 4-byte integer. 

On input This number indicates the entry at which reading begins. 

On output This number is adjusted by NAME _$READ_ DIR to a number suitable 

for a subsequent call to NAME _$READ_ DIR. 

To read from the start of the directory, initialize the index to 1 on your first call to 
NAME _ $READ _ DIR. 

Because NAME _$READ_ DIR adjusts the index parameter to a suitable value for a 
subsequent call, you should not change the value yourself. 
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NAME $READ DIR 



INPUT PARAMETERS 



max- count 

Maximum number of directory entries to read. This is a 2-byte integer. 



OUTPUT PARAMETERS 

read- count 

Number of directory entries actually read. This is a 2-byte integer. 

If NAME _$READ_ DIR reaches the end of the directory before finding the requested 
number of entries, read-count will contain the actual number of entries read, which will be 
smaller than the requested max-count. If there are no entries left in the directory prior to 
being called, NAME _$READ_ DIR returns a read-count of 0. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 



USAGE 

NAME _$READ_ DIR reads a directory and stores entry names, the length of each entry 
name, and the type of each entry. Pascal and C programs can access this information 
directly through the directory entry record structure. FORTRAN programs use the 
NAME _$EXTRACT_ DATA system call to access this information. 

The index argument pemits a program to make several calls to NAME _$READ_ DIR to 
ensure reading all entries. However, to get an accurate snapshot of a directory, make only 
one call to NAME _$READ_ DIR, using a sufficiently large max-count, because the 
contents of a directory can change between calls to NAME _$READ_ DIR. 
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NAME_ $READ _LINK 

NAME _ $READ _ LINK 

Returns the link text associated with a link name. 

FORMAT 

NAME_$READ_LINK (linkname, name-length, link-text, text-length, status) 

INPUT PARAMETERS 

linkname 

Name of the link, in NAME_$PNAME_T format. This is an array of up to 256 
characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 
of the pathname defaults to the current working directory. If a pathname is specified 
beginning with a slash (/), the entry directory of the local node is searched for the link. 

name- length 

Length of the linkname, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

link- text 

Text associated with the linkname, in NAME_$PNAME_T format. This is an array of 
up to 256 characters. 

text- length 

Length of the text, in bytes. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

When you use a linkname, the naming server replaces the link name with the associated 
link text. NAME _$READ_ LINK returns the text associated with a specified link name. 
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NAME_$SET_NDIR 

NAME_$SET_NDIR 

Sets the naming directory. 

FORMAT 

NAME_$SET_NDIR (name, name-length, status) 

INPUT PARAMETERS 

name 

Pathname of the desired naming directory, in NAME_$PNAME_T format. This is an 
array of up to 256 characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 
of the pathname defaults to the current working directory. A directory name beginning 
with a period (.) indicates a directory within the working directory. You may also specify a 
period by itself, which sets the naming directory equal to the working directory. 

name- length 

Length of the pathname, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

NAME_$SET_NDIR sets the naming directory to the specified directory. See the 
DOMAIN System Command Reference for a description of naming directories. 

This system call corresponds to the "ND directory-name" Shell command. 
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NAME_$SET_WDIR 

NAME_$SET_WDIR 

Sets the working directory. 

FORMAT 

NAME_$SET_WDIR (name, name-length, status) 

INPUT PARAMETERS 

name 

Pathname of the desired working directory, in NAME_$PNAME_T format. This is an 
array of up to 256 characters. 

Specify either an absolute or relative pathname. If a relative pathname is specified, the rest 
of the pathname defaults to the current working directory. A directory name beginning 
with a period (.) indicates a directory within the working directory. 

name- length 

Length of the name, in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the NAME 
Data Types section for more information. 

USAGE 

NAME_$SET_WDIR sets the working directory to the specified directory. See the 
DOMAIN System Command Reference Manual for a description of working directories. 

This system call corresponds to the "WD directory-name" shell command. 
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ERRORS 



STATUS_$OK 

Successful completion. 

NAME _ $ALREADY_EXISTS 
Name already exists. 

NAME _ $BAD _ DIRECTORY 
Bad directory. 

NAME _ $BAD _ LEAF 
Invalid leaf. 

NAME _ $BAD _ LINK 
Invalid link. 

NAME_ $BAD _PATHNAME 

Invalid pathname. / > 

NAME _ $DIRECTORY_FULL V ' 

Directory is full. 

NAME_ $DIRECTORY_NOT_EMPTY 
Directory is not empty. 

NAME _ $FILE _ NOT _ DIRECTORY 
Branch is not a directory. 

NAME_$ILL_LINK_OP 

Invalid link operation. 

NAME _ $INSUFFICIENT _ RIGHTS 
Insufficient rights. 

NAME _ $IS _ SYSBOOT 

Unable to delete system bootstrap (sysboot). 

NAME_$NO_RIGHTS 
No rights. 

NAME_$NODE_UNAVAILABLE 
Node is unavailable. 

NAME_$NOT_FILE 

Name is not a file. 

NAME_$NOT_FOUND 
Name not found. 

NAME _ $NOT _ LINK 

Name is not a link. 
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The PAD (Display Manager) programming calls allow you to create pads, windows, and window 
panes, and to manipulate text. This section describes their data types, call syntax, and error 
codes. Refer to the Introduction at the beginning of this manual for a description of data-type 
diagrams and call syntax format. 
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PAD DATA TYPES 



CONSTANTS 



MNEMONIC 
PAD_$BS 

PAD_$CPR_ALL 

PAD _ $CPR_ CHANGE 

PAD_$CPR_DRAW 

PAD_$CPR_FLAG 

PAD_$CPR_NONE 

PAD_$CPR_PICK 

PAD_$CR 

PAD_$ESCAPE 

PAD_$FF 

PAD_$LEFT_WINDOW 
PAD _ $MAX_TABSTOPS 
PAD $NEWLINE 



PAD $NO KEY 



PAD $TAB 



Value Explanation 

8 Moves the cursor one character position to the left 
if there is any room in the window. 

2 Cursor position report: Reports on each 
raw keystroke. 

1 Cursor position report: Reports only the changed 

position since the last output call or position report. 

4 Cursor position report: Reports on all 

touchpad data. 

16#FF Cursor position report: Indicates that the next 5 
bytes is a report. 

Cursor position report: Does not report any 

cursor positions. 

3 Cursor position report: Reports after cursor is 
settled when it has been moved by the touchpad. 

13 Returns cursor to the left edge of the pad at the 

same line it was on. 

27 For control characters: Tells Display Manager not 

to interpret the next character as a control 
character. This precedes ANSI escape sequences. 

12 Makes output start at the top of the window or 

window pane. 

16#FD Cursor position report: Indicates that the cursor 
accompanying the report is outside the window. 

100 Defines the maximum number of tabstops allowed 

to be set. 

10 Marks end of an input or output line, makes next 

text start on a new line. 

16#FE Cursor position report: Indicates that no keystroke 
accompanies the report. 

9 Moves cursor to next tab stop. 






DATA TYPES 



PAD $COORDINATE T 



2-byte integer for x and y bitmap coordinates. 
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PAD $CRE OPT T 



PAD $DISPLAY TYPE T 



A 2-byte integer. Options of a pane. Any 
combination of the following predefined values: 

PAD _$ABS_ SIZE 

Size parameter is absolute, rather than 

relative to the size of the existing pad. 

PAD_$INIT_RAW 

Input pad is initially raw, rather than normal 

(cooked) processing mode. 

A 2-byte integer. Type of display associated with 
the specified stream id. This is a 2-byte integer. 
One of the following predefined values: 



PAD_$BW_15P 

Black and white portrait display. 

PAD_$BW_19L 

Black and white landscape display. 



PAD $KEY DEF T 



PAD $KEY NAME T 



PAD_$COLOR_DISPLAY 

Color display (1024 x 1024 pixels). 

PAD_$800_COLOR 

Color display (1024 x 800 pixels). 

PAD_$NONE 
No display. 

An array of up to 256 characters. Display Manager 
command to be defined on a program- function key 
using PAD_$DEF_PFK. 

An array of up to 4 characters. Name of the 
program-function key to be defined using 
PAD_$DEF_PFK. 
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PAD $POSITION T 



X and y coordinates of a point on the display, 
diagram below illustrates the 
PAD_$POSITION_T data type: 



The 



V. 



predefined 
type 


byte: 
offset 

0: 
2: 




field name 




integer 


x_coord 




integer 


y_coord 



Field Description: 

y_ coord 

The y coordinate of the point on the display. 



PAD $REL ABS T 



x_ coord 

The x coordinate of the point on the display. 

A 2-byte integer. Indicates whether cursor 
movement is relative to the last location, or 
absolute. X and y are scaled. One of the following 
predefined values: 



PAD_$ABSOLUTE 

X and y are absolute values. Within a frame, 

movement is relative to the top left corner of 

the frame. Outside a frame, x is relative to 

the left end of the current line, and y is 

undefined. 



PAD_$RELATr/E 

Cursor movement is relative to the last 
location. X and y denote positive or negative 
offsets to the current cursor position. 



V. 
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PAD $SIDE T 



A 2-byte integer. Side of a transcript pad that a 
new pane occupies. One of the following predefined 
values: 



O 



PAD_$BOTTOM 

Bottom of transcript pad. 

PAD_$LEFT 

Left side of transcript pad. 

PAD_$RIGHT 

Right side of transcript pad. 

PAD_$TOP 

Top of transcript pad. 



o 



PAD $STRING T 



An array of up to 256 characters. String argument 
to some functions. 
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PAD $TABSTOP BUF T 



PAD $TYPE T 



PAD SWINDOW DESC T 



A 100-element array of 2-byte integers. Columns 
for tab stop settings. Each element contains a 
column number at which a tab stop will be set. 
Column numbers are scaled. 

A 2-byte integer. A type of pad. One of the 
following predefined values: 

PAD_$EDIT 
An edit pad. 

PAD_$INPUT 
An input pad. 

PAD_$TRANSCRIPT 
A transcript pad. 

PAD_$READ_EDIT 
A read/edit pad. 

Position of window on display screen. The diagram 
below illustrates the PAD _$WINDOW_ DESC _T 
data type: 



byte: 
offset 



0: 
2: 
4: 
6: 



15 



integer 



integer 



integer 



integer 



field name 

top 
left 
width 
height 



Field Description: 

top 

The y coordinate of the top left corner of the 

window, in raster units. 

left 

The x coordinate of the top left corner of the 

window, in raster units. 

width 

The width of the window, divided by the current 

x scale factor. 

height 

The height of the window, divided by the 

current y scale factor. 



PAD 
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PAD $WINDOW LIST T 



A 10-element array of 

PAD_$WINDOW_DESC_T record structures. 
The diagram below illustrates a single element: 



predefined 
type 



byte: 
offset 



0: 
2: 
4: 
6: 



15 



integer 



integer 



integer 



integer 



field name 

top 
left 
width 
height 



o 



top 

The y coordinate of the top left corner of the 

window, in raster units. 

left 

The x coordinate of the top left corner of the 

window, in raster units. 

width 

The width of the window, divided by the current 

x scale factor. 



height 

The height of the window, divided by the 

current y scale factor. 
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STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits are in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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PAD_$CLEAR_FRAME 

PAD _ $CLEAR_FRAME 

Clears the current frame, leaving it active. 

FORMAT 

PAD_$CLEAR_FRAME (stream-id, seek-key. status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$K)_T format. This is a 
2-byte integer. 

seek-key 

Unique value identifying the record where clearing begins, in STREAM_$ID_T format. 
This is a three element array of 4-byte integers. See the STREAM Data Types section for 
more information. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4-bytes long. See the PAD 
Data Types section for more information. 



USAGE 

Use this call to clear information from the frame that you created with the call, 
PAD _$ CREATE _ FRAME. Programs that use frames often overwrite text at random 
points within the frame. You should periodically call PAD _$CLEAR_ FRAME to remove 
this discarded data. By doing so, you prevent data from accumulating in the transcript pad 
file. You also prevent the Display Manager from invoking the time-consuming 
frame-rewrite operation. 

Clearing begins at the record indicated by the seek-key and continues to the end of the 
frame. If the first four bytes of the seek-key are 0, the entire frame is cleared. The seek-key 
is returned by STREAM _$PUT_REC and STREAM_$PUT_CHR. See the STREAM 
Calls section for more information. 
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PAD_$CLOSE_FRAME 

PAD_$CLOSE_FRAME r 

Closes a frame, leaving its contents in the pad, and returns to line-oriented processing on V 

the input pad. 

FORMAT 

PAD_$CLOSE_FRAME (stream-id. status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4-bytes long. See the PAD 
Data Types section for more information. 

USAGE 

After the frame is closed, you can view the frame by scrolling the transcript window 
backwards. Once the frame is closed, all frame operations except 
PAD $CREATE FRAME are invalid. 



V. 
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PAD_$COOKED 

PAD_$COOKED 

Disables raw mode input or output to a pad. 

FORMAT 

PAD_$COOKED (stream-id, status) 

INPUT PARAMETERS 

stream _ id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This call returns the pad to normal (cooked) processing if it is currently in raw mode due to 
a call to the PAD_$RAW procedure. PAD_$COOKED has no effect if called when the 
pad is not currently in raw mode. After you execute this procedure, the input window 
reappears and is empty. 



PAD- 11 PAD 



PAD $CPR ENABLE 



PAD _ $CPR_ENABLE 

Enables reporting of the keyboard cursor position for an input pad in raw mode. (You can 
only get keyboard cursor position reports on pads in raw mode). 

FORMAT 

PAD_$CPR_ENABLE (stream-id. report-cpr-type, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the input pad is open, in STREAM_$ID_T format. This 
is a 2-byte integer. 

report- cpr- type 

Type of cursor position report. This is a 2-byte integer. Specify one of the following 
predefined values: 

PAD _$CPR_ NONE 

Requests iio cursor position reports (the default). 

PAD _ $CPR _ CHANGE 

Requests cursor position reports only when the cursor has moved through 
keystrokes since the last output call or the last position report. 

PAD_$CPR_ALL 

Requests a cursor position report with every character. 

PAD_$CPR_PICK 

Requests a cursor position report after the cursor has settled after being 
moved by the touchpad, bitpad, or mouse. 

PAD_$CPR_DRAW 

Requests a cursor position report for all cursor positions during cursor 
movement from the touchpad, bitpad, or mouse. 

PAD_$CPR_PICK and PAD_$CPR_DRAW also report new cursor positions resulting 
from Display Manager commands; for example, arrow keys, tabs, TR, TL, TB. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 



V v 
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USAGE 



o 



You get cursor position reports in response to a STREAM_$GET_REC call, intermixed 
with raw character data. The Display Manager uses a single byte to represent a raw 
keystroke. It uses a 6-byte sequence to give you a cursor position report. The sequence looks 
like this: 

1 byte — PAD_$CPR_FLAG, indicating that the next 5 

bytes are a cursor position report. 

2 bytes — The x coordinate of the cursor position. 

2 bytes — The y coordinate of the cursor position. 

1 byte — The raw keystroke or PAD_$NO_KEY if there 
is no keystroke accompanying this cursor 
position report, or PAD_$LEFT_WINDOW if 
the cursor moved outside the window. 

The x and y coordinates are scaled according to the scaling factors in effect at the time of 
the PAD _$CPR_ ENABLE call (see PAD _$ SET _ SCALE). The x and y coordinates are 
relative to the upper left corner of the frame. (If the cursor is not inside a frame, the x 
coordinate is relative to the start of the current line, and the y coordinate is meaningless.) 

In raw mode, the Display Manager does not automatically echo typed keystrokes nor move 
the cursor. If your program requests PAD_$CPR_ALL but does not act to move the 
cursor (typically by displaying typed keystrokes), each keystroke produces a cursor position 
report, usually describing the same cursor position. If you don't intend to echo keyboard 
input, request PAD _$CPR_ CHANGE instead to avoid redundant cursor position reports. 

PAD _$CPR_ CHANGE compares the present keyboard cursor with the last output cursor 
position. In raw mode, the position of the output cursor is under program control. 
Therefore, if your program does not move the output cursor to follow the input cursor 
(which you can move) you may receive a stream of cursor position reports, all showing the 
same position, as long as the keyboard cursor is not in the same position as the output 
cursor. 
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PAD_$CREATE 

Creates a new pad and a window pane to view it. 

FORMAT 

PAD_$CREATE (pathname, name-length, pane-type, related-stream-id, side, 
pane_options, pane-size, pane-stream-id, status) 

INPUT PARAMETERS 

pathname 

Pathname to a file to display in the window pane, in NAME_$PNAME_T format. This is 
an array of up to 256 characters. 

If the specified pathname refers to an existing file, the Display Manager positions the new 
window pane at the beginning of the file, and displays any existing data. If the given 
pathname does not refer to an existing file, a permanent file with that name is created. 
You usually use a null pathname when creating a transcript pad. You must specify a null 
pathname when creating an input pad. 

name- length 

Length of the pathname in bytes. This is a 2-byte integer. A value of creates a temporary 
file for the pad. You must specify when creating an input pad. 

pane-type 

The window pane type in PAD_$TYPE_T format. This is a 2-byte integer. Specify one of 
the following predefined values: 

PAD_$EDIT Creates a pad in which you can view and modify the associated file. 

PAD_$INPUT Creates an input pad. 

PAD_$READ_EDIT 

Creates a pad in which you can view but not modify the associated file. 

PAD _ $TRANSCRIPT 

Creates a transcript pad. 

related- stream- id 

The stream ID of a transcript pad, in STREAM _$ID_T format. This is a 2-byte integer. 
The related-stream-id for an input window pane (PAD_$INPUT) must refer to an open 
transcript window pane that has no other input window pane associated with it. 
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side 

The side of the transcript pad that the new window occupies, in PAD_$SIDE_T format. 
This is a 2-byte integer. Specify one of the following predefined values: 

PAD_$LEFT 
PAD_$RIGHT 
PAD_$TOP 
PAD_$BOTTOM 

You must specify PAD_$BOTTOM when creating an input window pane for a transcript 
window pane. 

pane- options 

Attributes of the pane. This is a 2-byte integer. In Pascal, specify any combination of the 
following set of predefined values: 

PAD _$ABS_ SIZE 

Specifies an absolute pane-size. If not given, the pane-size parameter is a 
relative value. 

PAD_$INIT_RAW 

Indicates that a new input pad is initially in raw rather than cooked 
mode. This is for input pads only, it is invalid for any other pad types. 

In FORTRAN, specify either 0, to indicate that the pane-size is relative, or give the sum of 
the desired options. 

pane-size 

Size of the pane. This is a 2-byte integer. A window pane always takes up one full side of 
the related window. The size refers only to the depth of the window. 

You can express the pane size either as a percentage relative to the existing transcript 
window, or as an absolute value in terms of the current scale factor. 

If you specify the pane-size as an absolute size, the Display Manager attempts to keep the 
window pane at that size. However, the window pane can never be larger than the related 
window, so that, if the related window shrinks below the size requested, the window pane 
also shrinks. 

In addition, if you specify the pane size as an absolute size, the value given is multiplied by 
the current scale factors to yield raster units. The default scale factors are the current font 
size so that, unless you change the scale, you should express the pane-size in terms of lines 
or characters. 

An input window pane will normally be one line deep, but can grow and shrink depending 
on how many lines of input are waiting for action. You should specify a size that 
accommodates this because the size parameter determines the maximum number of lines 
that the input window pane can occupy. The size of an input window pane can never be 
less than 1. (A common relative size is 20. ) 
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OUTPUT PARAMETERS 

pane- stream- id 

Number of the stream on which the new window pane is open, in STREAM_$ID_T 
format. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types for more information. 



USAGE 

Use this call to create a new pad and window pane on a related stream. The related stream 
can be either the stream ID of a transcript pad that you previously created with a call to 
PAD_$CREATE or PAD _$CREATE_ WINDOW. For transcript pads, the stream ID 
can be a standard output stream such as STREAM_$STDOUT, or STREAM _$ERROUT. 

You can create any number of window panes on top of the original transcript pad up to the 
maximum of 40 pads and 60 windows. 

You must use PAD_$CREATE to create an input pad for an existing transcript pad. 



I, 
v.. 
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PAD_$CREATE_FRAME 

PAD _ $CREATE_FRAME 
Creates a frame in a pad. 

FORMAT 

PAD_$CREATE_FRAME (stream-id, width, height, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the input pad is open, in STREAM_$ID_T format. This 
is a 2-byte integer. 

width 

Width of the new frame in pixels. This is a 2-byte integer. Value can be up to 32767 raster 
units. Width is scaled according to the current scale factors. 

height 

Height of the new frame in pixels. This is a 2-byte integer. Value can be up to 32767 raster 
units. Height is scaled according to the current scale factors. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this call to create a frame on an existing transcript pad. Because you can move the 
cursor anywhere within the frame, create frames when you want to have more control over 
the cursor position in a given area of the screen. 

Your program must either close the frame with PAD _$CLOSE_ FRAME or delete the 
frame with PAD _$DELETE_ FRAME before exiting. (Note that you can review a closed 
frame by scrolling the transcript window backwards, but a deleted frame no longer exists.) 
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PAD _ $CREATE_ICON 

Creates a new pad and associated window in icon format. 

FORMAT 

PAD_$CREATE_ICON (pathname, name-length, type, unit, icon-pos, icon-char, 
window, stream-id, status) 

INPUT PARAMETERS 

pathname 

Pathname to a file to display in the pad, in NAME _ $PNAME _ T format. This is an array 
of up to 256 characters. 

If the specified pathname refers to an existing file, the Display Manager positions the new 
window pane at the beginning of the file, and displays any existing data. If the given 
pathname does not refer to an existing file, a permanent file with that name is created. 
You usually create a null pathname when creating a transcript pad. 

name- length 

Length of the pathname string. This is a 2-byte integer. A value of creates a temporary 
file for the pad. 

type 

Pad type in PAD_$TYPE_T format. This is a 2-byte integer. Specify one of the following 
predefined values: 

PAD_$TRANSCRIPT 

Creates a transcript pad. 

PAD_$EDIT Creates a pad in which you can view and modify the associated file. 

PAD_$READ_EDIT 

Creates a pad in which you can view but not modify the associated file. 

unit 

Display unit number associated with the stream- ID. This is a 2-byte integer. Usually, there 
is only one display per node so this value is often 1. 

icon-pos 

X- and y-coordinates of the upper left corner of the icon window, in PAD_$POSITION_T 
format. This data type is four bytes long. See the PAD Data Types section for more 
information. 

icon- char 

Icon font character to be displayed in the icon window. This character must reside in the 
current icon font file. A null character value (") causes the Display Manager to select the 
default icon character for this pad type. 



^ 
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window 

Window descriptor giving the position on the screen that the new window will occupy when 
expanded to full size (the icon window size is fixed by the the font character selected), in 
PAD_$WINDOW_DESC_T format. This data type is 8 bytes long. See the PAD Data 
Types section for more information. 

The window specified is the usable part of the displayed window. The displayed window is 
larger by the size of the border and the legend. If you specify either the width or the height 
as zero, the window is created using the same rules as for Display Manager commands (see 
the DOMAIN System Command Reference). 

OUTPUT PARAMETERS 

stream- id 

Number of the stream on which the new window is open, in STREAM_$ID_T format. 
This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 



USAGE 

Use this call to create a new pad and window in icon format. To change this window from 
icon format to a full-sized window, use PAD _$SELECT_ WINDOW. To change an 
existing window into icon format, use PAD _$MAKE_ ICON. 
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PAD _ $CREATE_ WINDOW 

PAD _ $CREATE_ WINDOW 

Creates a new pad and a window to view it. 

FORMAT 

PAD_$CREATE_WINDOW (pathname, name-length, pad- type, unit, window, 

stream-id, status) 

INPUT PARAMETERS 

pathname 

Pathname to a file to display in the pad, in NAME _$P NAME _T format. This is an array 
of up to 256 characters. When creating an edit or read/edit pad, this is the pathname of 
the permanent file for use as the pad. If a file with this name exists, the Display Manager 
positions the new window at the top of the pad. If such a file doesn't exist, a new file with 
that name is created. You usually use a null pathname when creating a transcript pad. 

name- length 

Length of the pathname string. This is a 2-byte integer. When creating an edit or read/edit 
pad, a value of creates a temporary file as the pad. 

pad-type 

Pad type in PAD_$TYPE_T format. This is a 2-byte integer. Specify one of the following 
predefined values: 

PAD_$TRANSCRIPT 

Creates a transcript pad. 

PAD_$EDIT Creates a pad in which you can view and modify the associated file. 

PAD_$READ_EDIT 

Creates a pad in which you can view but not modify the associated file. 

unit 

Display unit number to use. This is a 2-byte integer. Usually there is only one node per 
display so this value is often 1. 

window 

Window descriptor giving the position on the screen that the new window will occupy, in 
PAD_$WINDOW_DESC_T format. This data type is 8 bytes long. See the PAD Data 
Types section for more information. 

The window specified is the usable part of the displayed window. The displayed window is 
larger by the size of the border and the legend. If you specify either the width or the height 
as zero, the window is created using the same rules as for Display Manager commands (see 
the DOMAIN System Command Reference). 

OUTPUT PARAMETERS 

stream- id 

Number of the stream on which the new window is open, in STREAM_$K)_T format. 
This is a 2-byte integer. 
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status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 



USAGE 

Use this call to create a new pad and window to view it. Use PAD_$CREATE to create a 
new pad and window pane on an existing transcript pad. To create an input pad, you must 
use PAD $CREATE. 



o 
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PAD_$DEF_PFK 

Defines a program function key for use by a program. \_ 

FORMAT 

PAD_$DEF_PFK (stream-id, key-name, definition, def-len, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

key-name 

Name of the key to be defined. This is a 4-byte character array. Use the key name exactly 

as it appears in the DOMAIN System Command Reference. Use uppercase letters (for 

example, Fl) except when you are redefining a lowercase letter key (such as x). Do not use f 

quotes in this character array (except to redefine the quote key). V. 

definition 

Display Manager command you want executed whenever the specified key is pressed. This is 
an array of up to 128 characters. 

def-len 

Length of the definition in bytes. This is a 2-byte integer. A value of (zero) returns the 

key to its original definition. /'" 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE r 

\^ 

PAD_$DEF_PFK defines a program function key for use by a program. When you press 
a defined key, the definition string is entered as a Display Manager command. 

Program function keys defined by PAD_$DEF_PFK behave like keys defined through the 
Display Manager, except that the definition is only effective within windows viewing the 
associated pad. 

Definitions remain in effect after the program finishes executing, but only within windows 
viewing the pad associated with the program. 

The Display Manager command string you specify as the key definition is often the ES 

command, which contains a text string and lets the program function key simulate the 

typing of that text. You may specify the ER command, which introduces a two-digit 

hexadecimal number and feeds that value directly to the program when the user presses the 

key. The ER command essentially enables raw-mode input of the specified value, with no 

echoing or other processing by the Display Manager. The DOMAIN System Command ( 

Reference contains more details on these commands. ^- 
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The rules for naming keys in PAD_$DEF_PFK differ from the rules for naming keys in 
the KD (key definition) Display Manager command. That command implicitly converts 
letters to uppercase and allows the use of single quotes. 



O 
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PAD _ $DELETE _FRAME 

Deletes and clears the current frame. 

FORMAT 

PAD_$DELETE_FRAME (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD \ 

Data Types section for more information. 

USAGE 

PAD _$DELETE_ FRAME removes the current frame from the pad. After executing this 
procedure, the pad returns to line-oriented processing. You cannot perform further frame 
operations until you create another frame with a call to PAD _$ CREATE _ FRAME. 



_y 
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PAD_$DM_CMD 

Executes a Display Manager command. 

FORMAT 

PAD_$DM_CMD (stream-id, command, command-length, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which a pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

command 

Display Manager command, in PAD_$STRING_T format. This is an array of up to 256 
characters. 

command- length 

Length of the command string in bytes. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this procedure with caution since it performs actions that you normally perform with 
the keyboard. Because of this, PAD_$DM_CMD may produce unexpected results. 

You can find a list of Display Manager commands in the DOMAIN System Command 
Reference. 
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PAD_$EDIT_WAIT 

Suspends program execution until you close an edit window pane, then converts the stream 
so that the program can access the new input. 

FORMAT 

PAD_$EDIT_WAIT (pane-stream-id, status) 

INPUT PARAMETERS 

pane- stream- id 

Number of the stream on which the edit window is open, in STREAM_$E)_T format. 
This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Your program suspends execution until you close the edit window pane with a CTRL/Y 
(PW; WC -Q command) or a CTRL/N (WC -Q command). 

If you close the edit window pane with a CTRL/N, and the file did not exist before the edit 
window pane was created, PAD _$EDIT_ WAIT returns an error, usually indicating that 
the file was deleted while open. 

You must use this procedure before reading a file edited through an edit window pane. 



PAD PAD- 26 



o 



o 



o 



PAD _ $FORCE_PROMPT 

PAD _ $FORCE _PROMPT 

Forces an unterminated string to be written as a prompt in an input window. 

FORMAT 

PAD_$FORCE_PROMPT (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the input pad is open, in STREAM_$ID_T format. This 
is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This procedure forces the DM to display the last non-terminated string that was written to 
a transcript pad as the prompt in the related input pad. The string is not terminated with 
a PAD _$NEW_ LINE, which always forces the display of a string, and is usually intended 
as a prompt string. 

This procedure is no-op if the stream id is that of a raw input window. 
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PAD $ICON WAIT 



Waits until a window is expanded from an icon format to a full-window size or until the 
icon window moves. 



FORMAT 

PAD_$ICON_WAIT (stream-id, window-no. icon-moved, icon-pos, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

OUTPUT PARAMETERS 

icon-moved 

A Boolean value indicating icon-window movement. It returns a value of TRUE if the icon 
window has moved. 

icon-pos 

New position of the moved icon window in PAD_$POSITION_T format. This data type 
is 4 bytes long. See the PAD_$ Data Types section for more information. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This call may be used on any type of pad. 

If the window is not currently in icon format, this call returns immediately. 
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PAD _ $INQ _DISP _ TYPE 

Returns the type of display associated with the given stream ID. 

FORMAT 

PAD_$INQ_DISP_TYPE (stream-id. display- type, unit, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream associated with an input or transcript pad, in STREAM_$ID_T 
format. This is a 2-byte integer. 

OUTPUT PARAMETERS 

display-type 

Type of display associated with the specified stream ID, in PAD _$DISPLAY_ TYPE _T 
format. This is a 2-byte integer. Returns one of the following predefined values: 

PAD_$NONE No display 

PAD_$BW_15P 

Black and white portrait 

PAD_$BW_19L 

Black and white landscape 

PAD_$COLOR_DISPLAY 

Color display (1024 x 1024) 

PAD _ $800 _ COLOR 

Color display with fewer pixels (1024 x 800) » 

PAD _ $COLOR2 _DISPLAY 

Color display (1280x1024x8) 

PAD _ $COLOR3 _ DISPLAY 

Color display (1024x800x8) 

PAD _$COLOR4_ DISPLAY 

Color display (1024x800x4) 

unit 

Display unit number. This is a 2-byte integer. This parameter is reserved for future use, it 
will always have the value of 1. 

status 

Completion status, in STATUS __$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 
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USAGE 



PAD _$INQ_DISP_ TYPE returns the display type and unit number associated with the 
stream ID. The display unit number can be used as an argument to 
PAD $CREATE WINDOW. 
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PAD_$INQ_FONT 

PAD_$INQ_FONT 

Returns information about the current font. 

FORMAT 

PAD_$INQ_FONT (stream-id, font-width, font-height. 

font-name, font-size, font-len, status) 

INPUT PARAMETERS 

stream- id 

The number of the stream on which the pad is open, in STREAM_$ID__T format. This is 
a 2-byte integer. 

font-size 

The number of bytes available in the "font-name" string buffer. This is a 2-byte integer. 
PAD _$INQ_ FONT fills the "font-name" output parameter with this many characters of 
information. If you do not want to know the pathname, you can specify (zero) as the 
value of "font-size." 

OUTPUT PARAMETERS 

font-width 

Width of the font in raster units. This is a 2-byte integer. For fonts in which different 
characters have different widths, "font- width" describes the width of the space character. 

font- height 

Height of the font in raster units. This is a 2-byte integer. The height includes any interline 
spacing specified in the font file. 

font- name 

Full pathname of the font, up to the node entry directory (/), in PAD_$STRING_T 
format. This is an array of up to 256 characters. The pathname is returned with the 
correct character case (i.e., upper-case characters in the pathname are returned as 
upper-case; lower-case as lower-case). 

font-len 

Length of the "font-file" pathname. This is a 2-byte integer. If this value is greater than the 
input parameter "font-size," the Display Manager truncates the returned pathname. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this call to determine which font your program is currently using. Your program can 
use up to 100 different character fonts as long as you initially load all the fonts that you 
intend to use with PAD_$LOAD_FONT. When you want your program to use a specific 
font, call PAD_$USE_FONT to invoke a previously loaded font. Each time you want to 
change a loaded font, use PAD _$USE_ FONT. 
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PAD _ $INQ _FULL _ WINDOW 

Returns information about the entire window specified, including the border and legend. 

FORMAT 

PAD_$INQ_FULL_WINDOW (stream-id, window-no. window, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Window number of the window open on the pad. This is a 2-byte integer. Window number 
one always refers to the first window created to view the pad. 

OUTPUT PARAMETERS 

window 

Window descriptor giving the position on the screen that the window occupies, including the 
border and legend, in PAD_$WINDOW_DESC_T format. This data type is 8 bytes 
long. See the PAD Data Types section for more information. 

The window gives the position of the top left corner, width and height of the window. The 
values appear in the following order: top, left, width, height. All values are expressed in 
raster units. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this call to determine exactly how much screen space your window uses, including the 
border and legend. A call to PAD _$INQ_ WINDOWS returns similar information about 
the usable part of the display windows (not including the border and legend). 

Note that if the specified stream-id and window-no refer to a window pane, the information 
returned is for the outermost containing window. 
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PAD _$INQ_ ICON 

Returns information about a window in icon format. 

FORMAT 

PAD_$INQ_ICON (stream-id, window-no, icon-pos # icon-char, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

OUTPUT PARAMETERS 

icon-pos 

Position of the icon, in PAD_$POSITION_T format. This data type is 4 bytes long. See 
the PAD Data Types section for more information. 

icon- char 

Character currently displayed in the icon window. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

If the window is not currently in icon format, the information returned describes its 
previous icon status, if any, and its future icon status, should the Display Manager 
command ICON or the PAD _$MAKE_ ICON call be issued with the default setting for 
icon-pos and icon-char. 
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PAD_$INQ_ICON_FONT 

Returns information about the current icon font. 

FORMAT 

PAD_$INQ_ICON_FONT (stream-id, window-no, font-name 
font-buf-size, font-len, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM _$ID_T format. This is a 
2-byte integer. 

window-no 

• Window for which information is wanted. Window-no is an index into the window list 
returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. Window number one 
always refers to the first window created to view the pad. 

font-buf-size 

Number of bytes available in the font-name buffer string. This is a 2-byte integer. 
PAD_$INQ_FONT fills the output parameter, font-name, with this many characters of 
information. 

OUTPUT PARAMETERS 

font-name 

Pathname the font from the node entry directory (/), in NAME_$PNAME_T format. 
This is an array of up to 256 characters. The pathname is returned with the correct 
character case (i.e., upper-case characters in the pathname are returned as upper-case; 
lower-case as lower-case). 

font-len 

Length of the font file pathname. This is a 2-byte integer. If this value is greater than the 

input parameter font-size, the Display Manager truncates the returned pathname to fit in ( 

the smaller number of characters. v 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this call to get the pathname of the icon font in use. You can change the icon font in 
use with the call, PAD_$SET_ICON_FONT. 

The default icon font file is /SYS/DM/FONTS/ICONS. You can create a new icon font file 
to contain your own icons by using the font editor EDFONT. See the DOMAIN System 
Command Reference for a complete description of EDFONT. 
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PAD_$INQ_KBD 

Returns information about the keyboard currently in use. 

FORMAT 

PAD_$INQ_KBD (stream-id, buffer-size, kbd-suffix. length, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream associated with an input or transcript pad, in STREAM_$ID_T 
format. This is a 2-byte integer. 

buffer- size 

Number of bytes available in the "kbd-suffix" string buffer. This is a 2-byte integer. 

OUTPUT PARAMETERS 

kbd-suffix 

Suffix to be appended to Display Manager pathnames to locate a key definition file, in 
PAD_$STRING_T format. This is an array of up to 256 characters. Suffixes used by 
standard DOMAIN software are: 

Null string Corresponds to the 880 keyboard. 

Value of "2" Corresponds to the low-profile keyboard. 

Value of "3" Corresponds to the low-profile keyboard with numeric keypad. 

(Display Manager pathnames for key definitions are /SYS /DM/STD_ KEYS and 
USER_DATA/KEY_DEFS.) 

length 

Actual length of the string. This is a 2-byte integer. If the length parameter is greater than 
"kbd-suffix," it truncates "kbd-suffix." 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this call to determine which keyboard is in use. For example, you might want to set up 
program definition keys according to the type of keyboard in use. 
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PAD _ $INQ _POSITION 

PAD _ $INQ _POSITI0N 

Returns the position of the output cursor. 

FORMAT 

PAD_$INQ_POSITION (stream-id, x, y. status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

x 

X position of the output cursor. This is a 2-byte integer. 

y 

Y position of the output cursor. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

X and y are divided by the current scale factors. 

If this procedure is executed when the cursor is inside a frame, x and y are relative to the 
upper left corner of the frame. If the cursor is not in a frame, x represents the position on 
the line and y is undefined. 
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PAD _$INQ_ VIEW 

PAD _$INQ_ VIEW 

Returns information about the position of a window relative to a pad. 

FORMAT 

PAD_$INQ_VIEW (stream-id, window-number, line, eof-linenum, x-offset, 
y-offset, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream associated with an input or transcript pad, in STREAM_$ID_T 
format. This is a 2-byte integer. 

■w indow- numb er 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

OUTPUT PARAMETERS 

line 

Number of the line being viewed. This is a 4-byte integer. 

eof- linenum 

Last line or frame on the pad. This is a 4-byte integer. 

x-offset 

Distance the pad is horizontally scrolled. This is a 2-byte integer. 

y-offset 

Distance the pad is vertically scrolled. This is a 2-byte integer. Only frames can be 
vertically scrolled. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this routine in conjunction with PAD _$SET_ VIEW to control the display of graphic 
images that are larger than the window. PAD _ $INQ _ VIEW describes the pad element 
currently being viewed through the given window, usually a transcript pad element. 

If the element currently in view is a frame, x-offset and y-offset describe how the window is 
positioned in relation to the frame. If you are viewing the current frame and not some 
previous part of the pad, the value of eof-linenum will be equal to the line parameter. 

If the element currently in view is not a frame, the line parameter is the number of the top 
line in the window. 
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PAD _ $INQ _ WINDOWS 

PAD_$INQ_WINDOWS 

Returns information about windows viewing the current pad. 

FORMAT 

PAD_$INQ_WINDOWS (stream-id. windowlist, window-list-size, 
window-no, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-list-size 

Maximum number of windows on which information is desired. This is a 2-byte integer. 

OUTPUT PARAMETERS 

windowlist 

Information describing a window, in PAD _$WINDOW_ LIST _T format. This data type 
is an array of up to 10 elements, each of which is in PAD_$WINDOW_DESC_T format 
(four 2-byte integers). See the PAD Data Types section for more information. 

Windowlist indicates the top left corner and the width and height of each window open on 
the pad, up to wlistsize. The values appear in the following order: top, left, width, height. 
Top and left are expressed in raster units, but width and height are divided by the current 
scale factors. 

window-no 

The number of windows open on the pad. This is a 2-byte integer. Window number one 
always refers to the first window created to view the pad. Use this parameter in calls that 
require a window number. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 
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PAD_$IS_ICON 

PAD_$IS_ICON 

Checks if a window is in icon form. 

FORMAT 

is-icon = PAD_$IS_ICON (stream-id, window-no. status) 

RETURN VALUE 

is-icon 

A boolean value indicating whether or not the window associated with the stream is in icon 
form. 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the input pad is open, in STREAM_$ID__T format. This 
is a 2-byte integer. 

window- number 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information., 

USAGE 

The function returns TRUE if the window is an icon and FALSE if it is not. 
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PAD_$LOAD_FONT 

PAD_$LOAD_FONT 

Loads a character font. 

FORMAT 

PAD_$LOAD_FONT (stream-id, font-pathname, name-length, font-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

font- pathname 

Pathname of the file containing the character font, in PAD_$STRING_T format. This is 
an array of up to 256 characters. 

name- length 

Length of the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

font- id 

Font identifier, to be used in later calls to PAD _$USE_ FONT. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Your program can use up to 100 different character fonts as long as you initially load all 
the fonts that you intend to use with PAD _$LOAD_ FONT. When you want your 
program to use a specific font, call PAD _$USE_ FONT to invoke a previously loaded 
font. Each time you want to change a loaded font, use PAD _$USE_ FONT. To 
determine which font your program is currently using, call PAD_$INQ_FONT. 

The Display Manager first attempts to find the font file using the pathname directly, with 
the normal defaults. If it fails to find the file, it searches in /SYS/DM/FONTS. 

PAD _$LOAD_ FONT does not switch fonts. It merely loads the font into the invisible 
portion of display memory and returns a font ID. After loading the font, your program can 
call PAD _$USE_ FONT to use it. 

You can load up to 100 fonts in a given pad. 
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PAD_$LOCATE 

PAD_$LOCATE 

Returns the position of the keyboard cursor in response to a keystroke. 

FORMAT 

PAD_$LOCATE (stream-id. x, y, character, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM _$ED_T format. This is a 
2- byte integer. 

OUTPUT PARAMETERS 

x 

X position of the input cursor. This is a 2-byte integer. 

y 

Y position of the input cursor. This is a 2-byte integer. 

character 

Value of the key pressed. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This procedure returns the cursor position only when a raw character is entered. If the pad 
is in raw mode, any keystroke will do. In cooked mode, the ER command must be used. 
This command is usually entered through a function key definition. 

The keyboard cursor position must be within the transcript pad. 

X and y are divided by the current scale factors. 
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PAD_$MAKE_ICON 

Changes an existing window into icon format. 

FORMAT 

PAD_$MAKE_ICON (stream-id. window-no, icon-char, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

icon- char 

Icon font character to be displayed in the icon window. This character must reside in the 
current icon font. A (zero) causes the Display Manager to select the default icon character 
for this pad type. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This call changes an existing full-size window into icon format. (If the window is invisible at 
the time of the call, it first becomes visible and then becomes an icon.) To create a 
completely new pad and window in icon format, use PAD _$CREATE_ ICON. 

If the window is already an icon, this call has no effect. 

Specify the display position for the new icon using the PAD_$SET_ICON_POS routine 
before executing this call. If you do not do this, the Display Manager assigns a default icon 
position descriptor and font character. 

The size of the icon window is not user-definable. It is determined automatically by the size 
of the font character specified. 
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PAD _ $MAKE_INVISIBLE 

PAD _ $MAKE _ INVISIBLE 

Makes a visible window invisible. 

FORMAT 

PAD_$MAKE_INVISIBLE (stream-id, window-no, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

The effect of this call is the same as if the window were completely obscured by other 
windows on the screen, except that no amount of pushing, popping, moving, or growing can 
make it reappear. Only a subsequent call to PAD _$SELECT_ WINDOW will restore it to 
visibility in its full-size format. 

If the window is currently invisible, this call has no effect. 

If the window is currently in icon format, it will first be made into a full-size window and 
then turned invisible. 
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PAD_$MOVE 

Moves the output cursor. 

FORMAT 

PAD_$MOVE (stream-id, rel-abs, x, y. status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

rel-abs 

Indicates whether cursor movement is to be relative or absolute. This is a 2-byte integer in 
PAD_$REL_ABS_T format. Specify one of the following predefined values: 

PAD_$RELATIVE 

Movement is relative to the last cursor position. X and y denote positive 
or negative offsets to the current cursor position, scaled according to the 
current scale factors. 

PAD_$ABSOLUTE 

X and y are absolute, within the frame. X and y must be positive. 
Within a frame, movement is relative to the upper left corner of the 
frame. Outside a frame, x is relative to the left end of the current line 
and y is not used. In both cases, x and y are scaled according to the 
current scale factors. 



x 



y 



Change to the x-coordinate of the cursor position. This is a 2-byte signed integer. 
Change to the y-coordinate of the cursor position. This is a 2-byte signed integer. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

PAD_$MOVE changes the position of the output cursor, which marks the place where the 
next program output will appear. 

The cursor can move vertically only within a frame, not on a line. The Display Manager 
uses the y value only when a frame is active, and ignores it otherwise. 
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PAD_$POP_PUSH_WINDOW 

PAD_$POP_PUSH_WINDOW 
Pops or pushes a window. 

FORMAT 

PAD_$POP_PUSH_WINDOW(stream-id, window-no, flag, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM _$ID_T format. This is a 
2-byte integer. 

window-no 

The index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte 
integer. Window number one always refers to the first window created to view the pad. 

flag 

Indicates if the window is to be pushed or popped. This is a Boolean variable. A value of 
TRUE pops the specified window to the top of the screen, ensuring that no portion of the 
window is hidden by another window. A value of FALSE pushes the specified window to 
the bottom of the screen, allowing other windows to cover it wherever possible. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 
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PAD_$RAW 

Places an input or transcript pad in raw mode. 

FORMAT 

PAD_$RAW (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. The stream-id given should refer to an input stream, usually standard input 
(STREAM _$STDIN). PAD_$RAW has no effect on output. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

PAD _ $RAW puts the pad into raw mode, and has no effect if it is already in raw mode. 
PAD_$COOKED returns the pad to normal processing. 

In raw mode, the Display Manager sends keyboard input directly to the program without 
echoing or processing it in any way. ASCII control characters are also sent to the program, 
but the Display Manager still handles its function keys. 

The Display Manager immediately displays every character it receives, unless the window is 
in HOLD mode. If the window is in HOLD mode, new characters do not appear until the 
keyboard user scrolls the window or releases HOLD. 

When it executes this procedure, the Display Manager clears the input pad and shrinks its 
window size to zero. The keyboard cursor moves to the current output cursor position in 
the transcript pad. While the pad is in raw mode, the keyboard and output cursors usually 
move together. 

NOTE: A program using PAD_$RAW must execute PAD_$COOKED before 
termination. Most system utilities, including the Shell, will not work correctly in raw 
mode. 
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PAD $SELECT WINDOW 



PAD _ $SELECT _ WINDOW 

Makes an invisible window visible and/or changes an icon-format window into a full-sized 
window. 



FORMAT 

PAD_$SELECT_WINDOW (stream-id, window-no. status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window- no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use PAD _$MAKE_ INVISIBLE to make windows invisible. 

If this call is used to expand an icon to full-size format, the position and dimensions of the 
large window are the same as those it had when it was last full size. If it was never full-size, 
its position and dimensions are those specified (or defaulted) when the icon was created 
(either by PAD _$CREATE_ ICON, or by the Display Manager commands CP, CV, CE, 
or CPB with the -I option specified). 
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PAD _ $SET _ AUTO _ CLOSE 

Sets a window to close automatically when its pad closes. 

FORMAT 

PAD_$SET_AUTO_CLOSE (stream-id, window-no. auto-close, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

auto- close 

Indicates whether the window is to close automatically. This is a Boolean value. If TRUE, 
the window disappears when the pad onto which it opens is closed. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

When a program first makes this call and then does a STREAM _$CLOSE, the window 
specified is closed and deleted from the screen. This is equivalent to specifying the Display 
Manager command WC -A for a window. 
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PAD _ $SET _ BORDER 

Adds a border to, or removes the border from, a full window. 

FORMAT 

PAD_$SET_BORDER (stream-id. window-number, flag, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window- number 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

flag 

Indicates whether to add or remove a border. This is a Boolean variable. If TRUE, the 
window appears with a border around its edges and a legend at the top. If FALSE, any 
border and legend are removed from the window, making the window's usable area equal to 
the amount of space the window occupies on the screen. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this procedure to remove or add a border to a full window that has no other panes 
associated with it. If you add a pane to a window from which the border was removed, the 
border will be redrawn. Likewise, if you change the input pad mode to cooked, the border 
will be redrawn. 

To get a full window without any panes, you can either create a transcript pad and never 
make a PAD_$CREATE call to add panes, or create a transcript pane that covers the 
entire window. Another way to get a full window is to make an input pane invisible by 
using the PAD_$RAW call. 
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PAD _ $SET _FULL _ WINDOW 

Moves a window or sets a window position for future use. 

FORMAT 

PAD_$SET_FULL_WINDOW (stream-id, window-no. window, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the first window created to view the pad. 

window 

Window descriptor giving the position on the screen that the new window will occupy when 
expanded to a full-sized window, in PAD_$WINDOW_DESC_T format. This data type 
is 8 bytes long. See the PAD_$ Data Types section for more information. 

The window specified is the entire window, including the border, legend, and usable part of 
the window. The call, P AD _$ INQ_ FULL _ WINDOW returns information about the 
entire window. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

If the window specified is currently in icon format or is invisible, this call establishes a 
full-size window position for future use (i.e., when your program calls 
PAD _$SELECT_ WINDOW to expand the icon into a full-size window, or you issue the 
Display Manager commands ICON or WI). 

If the window specified is currently full-size, then the window is repositioned to the location 
given by window. 
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PAD_$SET_ICON_FONT 

PAD_$SET_ICON_FONT 

Sets the current icon font to a specified font name. 

FORMAT 

PAD_$SET_ICON_FONT (stream-id, window-no, font-name, 
font-len, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Window whose icon font you want to change. Window-no is an index into the window list 
returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. Window number one 
always refers to the first window created to view the pad. 

font-name 

Full pathname of the font, up to the node entry directory (/), in NAME_$PNAME_T 
format. This is an array of up to 256 characters. 

font-len 

Length of the font file pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this call to change the icon font in use. This call changes the font of the specified 
window only. 

When a window is created either as a full window or an icon, the Display Manager assigns 
it an icon from "active icon font." The default active icon font is in 
/SYS/DM/FONTS/ICONS. You can specify another font to be the active icon font by 
using the FL command with the -I option. 

You can create a new icon font file to contain your own icons by using the font editor 
EDFONT. See the DOMAIN System Command Reference for a complete description of 
EDFONT. 

If the window is in icon format at the time of this call, the icon in the display changes to 
the new font immediately. 
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PAD_$SET_ICON_POS 

Moves an icon or sets an icon position for future use. 

FORMAT 

PAD_$SET_ICON_POS (stream-id, window-no, icon-pos, icon-char, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

window-no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte integer. 
Window number one always refers to the original transcript pad. 

icon-pos 

New position (x and y coordinates) of the icon, in PAD_$POSITION_T format. This data 
type is 4 bytes long. See the PAD Data Types section for more information. 

icon- char 

Character to be displayed in the icon window. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

If the window specified is currently in full-size format, this call establishes an icon position 
for future use (i.e., when your program calls PAD _$MAKE_ ICON to turn the window 
into icon format, or you use the Display Manager command ICON). 

If the window specified is already in icon format, then the icon is repositioned to the 
location given by icon-pos, and the specified icon-char replaces the current one. 

Compare this call to PAD _$SET_ FULL _ WINDOW, which performs the same operations 
for full-size windows. 

The size of the icon window is not user-definable. It is determined automatically by the size 
of the font character specified. 
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PAD _$SET_ SCALE 

PAD _$SET_ SCALE 

Sets a scale factor for cursor operations. 

FORMAT 

PAD_$SET_SCALE (stream-id, x-f actor, y-f actor, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM _$H)__T format. This is a 
2-byte integer. 

x- factor 

Scale factor for the x-coordinate. This is a 2-byte integer. 

y- factor 

Scale factor for the y-coordinate. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Specify a scale factor of zero to use the scale of the current character font. This is the 
default. 

Specify a nonzero scale factor to use that number as a multiplier for raster units. One 
raster unit is equal to one bit in the display. 

The scale factor is used to convert between raster units and numbers supplied in routines 
such as PAD_$MOVE. When using the scale of the current font, you express dimensions 
in terms of characters and lines. In any case, the numbers you enter are multiplied by the 
scale factor to yield raster units, and raster units are divided by the scale factor before 
being returned. 

The scale factor is used to process input or output for PAD _$CPR_ ENABLE, 
PAD_$CREATE_FRAME, PAD_$INQ_POSITION, PAD_$LOCATE, 
PAD_$MOVE, and PAD _$INQ_ WINDOWS. In PAD _$INQ_ WINDOWS, height and 
width are scaled, but top and left are not. PAD _$INQ_ FONT always returns dimensions 
in terms of raster units. 

The scale factors set with this call apply to the specified stream until specifically reset, even 
after the calling program ends. Your program should not depend on the scale factors being 
correctly set, but should call PAD _$SET_ SCALE to explicitly set the scale factors as 
desired. 
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PAD_$SET_TABS 

Sets tab stops within a pad. 

FORMAT 

PAD_$SET_TABS (stream-id, tab-stop-array, no-of-tabs, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

tab- stop- array 

Columns for tab stops. This is an array of up to 100 2-byte integers. Each element in the 
array contains a column number at which a tab stop will be set. Column numbers are 
scaled according to the PAD _$SET_ SCALE procedure. 

For example, assume that the current vertical and horizontal scale factors are both equal to 
one. A three-element array containing the integers 100, 300, and 500 would specify tab 
stops at bit positions 100, 300, and 500 on the screen. Because the display contains 
approximately 100 bits per inch, these tab stops would be set about 1, 3, and 5 inches (2.54, 
7.62, and 12.70 cm) from the left edge of the screen. 

no-of-tabs 

Number of tab stops set. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This procedure sets tabs only for the pad open on the specified stream. Tab stops for all 
other pads are unchanged. 

The default tab setting has tabs every 4 columns. 
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PAD_$SET_VIEW 

PAD_$SET_VIEW 

Positions a window to establish a given view. 

FORMAT 

PAD_$SET_VIEW (stream-id. window-no, line, x-offset, 
y-offset, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream ssociated with a transcript pad, in STREAM_$ID_T format. Th^s 
is a 2-byte integer. 

window-no 

Index into the window list returned by PAD _$INQ_ WINDOWS. This is a 2-byte 
integer .Window number one always refers to the first window created to view the pad. 

line 

Line number to view. This is a 4-byte integer. 

x- offset 

Distance to scroll the pad horizontally. This is a 2-byte integer. 

y-offset 

Distance to scroll the pad vertically (for frames only). This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This routine repositions a window to establish a particular view of a transcript pad. 
Programs can call this routine after a call to PAD _$INQ_ VIEW and in conjunction with 
calls to PAD _$INQ_ WINDOWS to control the display of graphic images that are larger 
than the window. 
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PAD_$USE_FONT 

PAD_$USE_FONT 

Invokes a loaded font. V^. 

FORMAT 

PAD_$USE_FONT (stream-id, font-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream on which the pad is open, in STREAM_$ED_T format. This is a 
2-byte integer. 

font- id 

Font identifier returned by PAD_$LOAD_FONT. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

Use this call to change your program's current character font. 

Your program can use up to 100 different character fonts as long as you initially load all 
the fonts that you intend to use with PAD_$LOAD_FONT. When you want your 
program to use a specific font, call PAD_$USE_FONT to invoke a previously loaded 
font. Each time you want to change a loaded font, use PAD _$USE_FONT. To 
determine which font your program is currently using, call PAD_$INQ_FONT. 

NOTE: Use PAD_$USE_FONT only to change the current font in use. You will get 
erroneous results if the call specifies the font that is already currently in use. 
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ERRORS 

STATUS _$OK 

Successful completion. 

PAD _ $2MNY_ CLIENTS 

Operation illegal with more than one client process. 

PAD _ $2MNY_ INPUT _PADS 

Only one input pad per transcript. 

PAD _ $BAD _KEY_ NAME 

Key name not found. 

PAD _$EDIT_ QUIT 

User quit (WC -Q) out of edit pane. 

PAD _ $FONT _ FILE _ ERR 

Could not access font file. 

PAD_$ID_OOR 

Stream id out of range. 

PAD _ $ILL _ PARAM _ COMB 

Conflict in PAD_$CREATE call. 

PAD_$ILL_PTYPE 

Cannot do operation on this type of pad. 

PAD_$NO_SUCH_WINDOW 

Bad window number in INQ/SET_VIEW. 

PAD _ $NO _ WINDOW 

Window no longer exists. 

PAD _$NOT_ ASCII 

Existing pad in PAD_$CREATE is not ASCII. 

PAD _ $NOT _ INPUT 

Operation valid on input pads only. 

PAD_$NOT_RAW 

Operation requires pad be in raw mode. 

PAD _ $NOT _ TRANSCRIPT 

Operation valid on transcript pads only. 

PAD_$STREAM_NOT_OPEN 

No stream open on this SID. 

PAD _ $STREAM _ NOT _ PAD 

Preferred stream is not a pad. 

PAD_$TOO_MANY_FONTS 

Too many fonts loaded in this pad. 

PAD_$VOOR 

Value out of range. 
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The PBUFS (Paste Buffer) programming calls maintain cut-and-paste buffers for data 
interchange between applications and the Display Manager. This section describes their error 
messages and call syntax. The PBUFS calls do not use unique data types. Refer to the 
Introduction at the beginning of this manual for a description of call syntax format. 
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PBUFS_$CREATE 

PBUFS_$CREATE 

Creates a paste buffer. 

FORMAT 

PBUFS_$CREATE (buffer-name/ type, stream-id. status) 

INPUT PARAMETERS 

buffer-name 

Name of the paste buffer you want to create (not a pathname), in NAME_$NAME_T 
format. This is an array of up to 32 characters. This array must be a full 32 bytes, padded 
with blanks. See the NAME Data Types section for more information. 

type 

Indicates whether the paste buffer is to hold text or pictures. This is a Boolean value. 
TRUE designates a text buffer. FALSE designates a GMF buffer that can hold images. 

OUTPUT PARAMETERS 

stream- id 

Number of a stream with which to refer to the new paste buffer, in STREAM_$ID_T 
format. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This call creates a paste buffer of the specified name and type in the directory 

'node _ data/paste _ buffers. An error occurs if the named paste buffer already exists in 

/sys/node _ data/paste __ buffers. 

The file has the temporary attribute, STREAM_$IRM_ TEMPORARY. The system will 
delete this file when you close the stream, unless you call STREAM _$REDEFINE to 
change the file's attributes first. 

Calling PBUFS_$CREATE opens the stream for overwrite access 
(STREAM_ $OVERWRITE). 

You can call STREAM_$ CREATE, specifying a pathname in 
/sys/node _ data/paste _ buffers to achieve the same effect. 
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PBUFS_$OPEN 

PBUFS_$OPEN 

Opens a pre-existing paste buffer. 

FORMAT 

PBUFS_$OPEN (buffer-name, type, stream-id. status) 

INPUT PARAMETERS 

buffer- name 

Name of the paste buffer you want to open (not a pathname), in NAME_$NAME_T 
format. This is an array of up to 32 characters. This array must be a full 32 bytes, padded 
with blanks. See the NAME Data Types section for more information. 

type 

Indicates whether the paste buffer is to hold text or pictures. This is a Boolean value. 
TRUE designates a text buffer. FALSE designates a GMF buffer that can hold images. The 
value you specify must match the value used when creating the paste buffer, or the paste 
buffer manager returns the completion status PBUFS_$WRONG_TYPE. 

OUTPUT PARAMETERS 

stream- id 

Number of the stream with which to refer to the paste buffer, in STREAM_$ID_T 
format. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PAD 
Data Types section for more information. 

USAGE 

This call open a pre-existing paste buffer of the specified name and type in the directory 
'node _ data/paste _ buffers. 

An error occurs if the named paste buffer does not already exist in 
/sys/node_ data/paste _ buffers. Use PBUFS_$CREATE to create a buffer. 

You can call STREAM _$OPEN, on a file in /sys/node_ data/paste _ buffers, to achieve 
the same effect. 
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PBUFS ERRORS 



ERRORS 



PBUFS _ $WRONG _ TYPE 

The actual buffer type differs from the type specified. 
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PFM 



The PFM (Process Fault Manager) programming calls control signals, faults, and exceptions for 
faults. This section describes their data types, call syntax, and error codes. Refer to the 
Introduction at the beginning of this manual for a description of data-type diagrams and call 
syntax format. 
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PFM DATA TYPES 



CONSTANTS 



PFM $ALL FAULTS 



Specified when establishing a handler to catch 
all faults. 
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DATA TYPES 



PFM_ $CLEANUP _REC 
PFM_$FAULT_FUNC_P_T 

PFM $FAULT REC T 



Cleanup routine information, 64 bytes long. 

A 4-byte integer. A pointer to a fault handler 
function. 

Parameter to fault handler function. The diagram 
below illustrates the PFM_$FAULT_REC_T 
data type: 



predefined 
type 


byte: 
offset 

0: 
2: 






field name 




integer 




pattern 




integer 


status 



Field Description: 

pattern 

Reserved for PFM use. 



PFM $FH FUNC VAL T 



status 

The returned status in STATUS _$T format. 

A 2-byte integer. Specifies action to be taken when 
handler completes. One of the following predefined 
values: 



PFM_$CONTINUE_FAULT_HANDLING 
Specifies that the fault be passed to next 
handler. 



PFM_$FH_HANDLE_T 
PFM $FH OPT SET T 



PFM_$RETURN_TO_FAULTING_CODE 
Specifies that control be returned to the 
program. 

A 4-byte integer. Pointer to a fault handler. 

A 2-byte integer. Options for type of handler to 
establish. Any combination of the following 
predefined values: 
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PFM DATA TYPES 



PFM _ $FH _ BACKSTOP 

specifies that the handler should be called 

after all other handlers. 



STATUS $T 



PFM_$FH_MULTI_LEVEL 

Specifies that handler applies to faults on its 

program level, and all subordinate levels. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



o 



o 



byte: 
offset 


31 






field name 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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PFM_$CLEANUP 

PFM_$CLEANUP 

Establishes a clean-up handler for faults. 

FORMAT 

status = PFM_$CLEANUP (clean-up-record) 

RETURN VALUE 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PFM 
Data Types section for more information. 

When initially called to establish a clean-up handler, PFM_$CLEANUP returns the status 
PFM_$CLEANUP_SET. After a fault occurs, PFM_$CLEANUP returns the status of 
the fault, or the status signaled by PFM_$SIGNAL or PFM _$ERROR_ TRAP. 

OUTPUT PARAMETERS 

clean-up- record 

A record uniquely identifying the clean-up handler, in PFM_$CLEANUP_REC format. 
This data type is 8 bytes long. See the PFM Data Types section for more information. 

This parameter is passed as input to the PFM_$RLS_ CLEANUP and 

PFM _$RESET_ CLEANUP procedures in order to specify a particular handler. Your 

program cannot modify or copy this value. 

USAGE 

PFM_$CLEANUP establishes a clean-up handler that is executed when a fault occurs. 
Clean-up handlers let the program "clean up" a task, possibly notifying you of the error 
condition and leaving any open files in a known and stable state. 

You may establish more than one clean-up handler. Multiple cleanup handlers are executed 
consecutively, starting with the most recently established handler and continuing backward 
in time (LIFO). A built-in clean-up handler is always established when you invoke your 
program. This built-in handler is always called last. It closes any files that are still open 
and returns control to the invoking Shell. 

The initial call to PFM _$ CLEANUP establishes the clean-up handler and returns a status 
value of PFM_$CLEANUP_SET. When a fault occurs, execution returns to the most 
recent PFM_$CLEANUP call. The clean-up handler associated with that call is then 
removed from the stack and executed. 
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PFM $ENABLE 



PFM_$ENABLE 

Enables asynchronous faults. 

FORMAT 

PFM_$ENABLE 

USAGE 

PFM_$ENABLE enables asynchronous faults after they have been inhibited by a call to 
PFM_$INHIBIT. PFM_$ENABLE causes the operating system to pass asynchronous 
faults on to the program. 

While faults are inhibited, the operating system holds at most one asynchronous fault. So, 
as soon as a PFM_$ENABLE executes, your program receives one asynchronous fault. If 
more than one fault occurred while faults were inhibited, the program receives the first 
asynchronous fault. 

Since a user cannot terminate a program while PFM_$INHIBIT is in effect, it is good 
programming practice to inhibit asynchronous faults only during critical intervals, or enable 
faults occasionally to allow users to exit. 
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PFM_$ERROR_TRAP 

PFM_$ERROR_TRAP 

Simulates a fault with a given status code, storing traceback information. 

FORMAT 

PFM_$ERROR_TRAP (status) 

INPUT PARAMETERS 

status 

Error code, in STATUS _$T format. This data type is 4 bytes long. See the PFM Data 
Types section for more information. 

USAGE 

Use this procedure to force an error exit with the specified status code, or in a fatal error 
situation where no status code otherwise returns. One possible use is in defining your own 
error condition. 

This procedure differs from PFM_$SIGNAL in that traceback information is stored, so 
that it is possible to determine where the fault occurred. 
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PFM_ $ESTABLISH_FAULT_HANDLER 

PFM_$ESTABLISH_FAULT_HANDLER 
Establishes a fault handler. 

FORMAT 

handler-id = PFM_$ESTABLISH_FAULT_HANDLER (target-status, options, 

function-pointer, status) 

RETURN VALUE 

handler- id 

A value uniquely identifying the established handler, in PFM_$FH_ HANDLE _T format. 
This is a 4-byte integer. 

You pass this value to the PFM_$RELEASE_FAULT_ HANDLER call when you want to 
release the handler. 



o 



o 



INPUT PARAMETERS 

target- status 

A value specifying the type of fault that causes this handler to take effect. This is a 4-byte 
integer. 

To establish a fault handler for all faults produced by a certain DOMAIN module, use any 
error status code returned by that module, with the fault code field set to 0. To establish a 
fault handler that handles all faults, use the constant PFM_$ALL_ FAULTS. 

options 

A value specifying the type of handler you want to establish, in 

PFM_$FH_OPT_SET_T format. This is a 2-byte integer. Specify any combination of 
the following set of predefined values: 

PFM_$FH_MULTI_LEVEL 

To declare a multilevel fault handler that handles faults for its own 
program level and all subordinate levels. 

PFM_$FH_BACKSTOP 

To establish a backstop fault handler that takes effect after all nonbackstop handlers have 
taken effect. 

(In FORTRAN, you can combine these options by adding the constants.) 

function-pointer 

The address of the fault handler for the specified type(s) of faults, in 
PFM_$FAULT_FUNC_P_T format. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PFM 
Data Types section for more information. 
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PFM $ESTABLISH FAULT HANDLER 



This call establishes a fault handler, making it take effect for all the faults of the specified 
type or types that occur after the time of the call. 

The fault handler remains in effect until you release it using 

PFM _$RELEASE_ FAULT _ HANDLER or until the program ends. 
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PFM_$INHIBIT 

Inhibits asynchronous faults. 

FORMAT 

PFM_$INHIBIT 

USAGE 

PFM_$INHIBIT prevents asynchronous faults from being passed to the program. Use this 
call when an interval of your program cannot be interrupted, for example, when performing 
I/O. Use the complementary PFM_$ENABLE call to re-enable asynchronous faults. 

Asynchronous faults are produced from outside your program and are unrelated to anything 
within your program. They can occur at any point during your program's execution. A 
common example of an asynchronous fault is the Display Manager quit (DQ) command that 
occurs when someone types a CTRL/Q to stop a program. 

Since a user cannot terminate a program while PFM_$INHIBIT is in effect, it is good 
programming practice to inhibit asynchronous faults only during critical intervals. 

While faults are inhibited, the operating system holds at most one asynchronous fault. So, 
as soon as a PFM_$ENABLE executes, your program receives one asynchronous fault. If 
more than one fault occurred while faults were inhibited, the program receives the first 
asynchronous fault. 

Inhibiting asynchronous faults has no effect on the processing of synchronous faults such as 
floating-point overflow errors, access violations, address errors, and so on. 
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PFM_$RELEASE_FAULT_HANDLER 

PFM_$RELEASE_FAULT_HANDLER 
Releases a fault handler. 

FORMAT 

PFM_$RELEASE_FAULT_HANDLER (handler-id, status) 

INPUT PARAMETERS 

handler- id 

A value uniquely identifying the handler, in PFM_$FH_ HANDLE _T format. This is a 
4-byte integer. 

A unique value is returned by PFM_$ESTABLISH_ FAULT _ HANDLER each time you 
establish a handler. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PFM 
Data Types section for more information. 



USAGE 

This call causes the specified fault handler to cease having effect for faults that occur after 
the time of the call. 

You should note that you cannot release a fault handler that is installed inside a fault 
handler. 

To establish a fault handler, use the PFM _$ESTABLISH_ FAULT _ HANDLER call. 
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PFM_ $RESET_ CLEANUP 

PFM_ $RESET_ CLEANUP 

Returns a clean-up handler to the top of the handler stack. 

FORMAT 

PFM_$RESET_CLEANUP (clean-up-record, status) 

INPUT PARAMETERS 

clean- up- record 

A record uniquely identifying the clean-up handler, in PFM_ $ CLEANUP _REC format. 
This data type is 8 bytes long. See the PFM Data Types section for more information. 

A unique record is returned by PFM_$CLEANUP each time a cleanup handler is 
established. The clean-up-record that is input must not have been altered or copied. If it 
has been, or if for some other reason the record is invalid, the procedure will fail with the 
status PFM_$INVALID_ CLEANUP _REC. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PFM 
Data Types section for more information. 

USAGE 

This procedure re-establishes the clean-up handler identified by the clean-up-record at the 
top of the stack, so that any subsequent errors invoke it first. 

This procedure can only be used within a clean-up handler. 
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PFM_ $RLS _ CLEANUP 

PFM _ $RLS _ CLEANUP 

Releases a specified clean-up handler and any other clean-up handlers above it on the stack. 

FORMAT 

PFM_$RLS_CLEANUP (clean-up-record, status) 

INPUT PARAMETERS 

clean- up- record 

A record uniquely identifying the clean-up handler, in PFM _$ CLEANUP _REC format. 
This data type is 8 bytes long. See the PFM Data Types section for more information. 

A unique record is returned by PFM_$CLEANUP each time a clean-up handler is 
established. The clean-up-record that is input must not have been altered or copied. If it 
has been, or if for some other reason the record is invalid, the procedure will fail with the 
status PFM_$INVALID_CLEANUP_REC. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PFM 
Data Types section for more information. 

Possible status values are: 

PFM_$INVALID_$CLEANUP_REC 

The clean-up-record has been altered or copied and is therefore invalid. 

PFM_$BAD_RLS_ORDER 

Program attempting to release a clean-up handler before releasing all 
handlers established after it. This status is only a warning; the handler is 
successfully released, and all handlers above it on the stack are also 
released. 

USAGE 

PFM_$RLS_ CLEANUP releases the specified clean-up handler and all other clean-up 
handlers above it on the stack. 
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PFM_$SIGNAL 

Exits from the current procedure and signals a status for the clean-up handler on the top of 
the stack. 



FORMAT 

PFM_$SIGNAL (status) 

INPUT PARAMETERS 

status 

Status code,. in STATUS _$T format. This data type is 4 bytes long. See the PFM Data 
Types section for more information. 

USAGE 

PFM_$SIGNAL can be called from within a clean-up handler or from normal code. 

If invoked from within a clean-up handler, PFM_$SIGNAL exits from the current clean-up 
handler and invokes the clean-up handler on the top of the stack, if there is one. If invoked 
from outside a clean-up handler, this routine invokes the top clean-up handler on the stack, 
with the status code given in the PFM_$SIGNAL call. 

Typically, PFM_$SIGNAL is called at the end of one clean-up handler to invoke the next 
handler, and the status parameter is normally assigned the error status originally received 
from PFM_$CLEANUP. When no more clean-up handlers from the current program are 
on the stack, PFM_$SIGNAL causes the program to exit to the invoking program (which 
may be the Shell) with the status code set to the value given in the status parameter. 

Traceback information (see the DOMAIN System Command Reference) is not stored when 
PFM_$SIGNAL is called. When a fault occurs, however, the operating system 
automatically stores traceback information. 

Unlike most subroutines, PFM_$SIGNAL does not return to the place from which it was 
called. 
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ERRORS 

STATUS _$OK 

Successful completion. 

PFM _ $BAD _ RLS _ ORDER 

Cleanup handler released out of order. 

PFM_$CLEANUP_NOT_FOUND 

Static cleanup handler not found. 

PFM_$CLEANUP_SET 

Cleanup handler established successfully. 

PFM _ $ CLEANUP _ SET _ SIGNALLED 

PFM_$CLEANUP_SET was signalled. 

PFM_$FH_NOT_F0UND 

Attempt to release non-existent fault handler. 

PFM_$FH_WRONG_LEVEL 

Attempt to release fault handler at wrong level. 

PFM_ $INVALID _ CLEANUP _REC 
Invalid clean-up record. 

PFM _$NO_ SPACE 

No RWS space to create static clean-up handler. 
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The PGM (Program Manager) programming calls load programs, start execution, and perform 
cleanup. This section describes their data types, call syntax, and error codes. Refer to the 
Introduction at the beginning of this manual for a description of data-type diagrams and call 
syntax format. 
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PGM DATA TYPES 



CONSTANTS 

PGM_$ERROR 

PGM_$FALSE 

PGM_ $INTERNAL_FATAL 

PGM_$MAX_SEVERITY 

PGM_$OK 

PGM_$OUTPUT_ INVALID 

PGM_$PROGRAM_FAULTED 

PGM_$TRUE 

PGM $WARNING 



3 The error severity level. 

1 A test severity level. 

5 The fatal severity level. 
15 The highest severity level. 
The success severity level. 

4 A conditional severity level. 

6 The program fault severity level. 
A test severity level. 

2 The warning severity level. 



DATA TYPES 



EC_$PTR_T 

EC2 $EVENTCOUNT T 



A 4-byte integer. Pointer to an eventcount. 

User eventcount. The diagram below illustrates the 
EC2_$EVENTCOUNT_T data type: 



predefined 
type 


byte: 
offset 

0: 
4: 






field name 




integer 


value 




integer 




awaiters 



Field Description: 

value 

Current EC value. 

awaiters 

First process waiting. 
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PGM $ARG 



An argument returned by PGM_$GET_ARGS. 
The diagram below illustrates the PGM_$ARG 
data type: 



predefined 
type 


byte: 
offset 

0: 
2: 

n: 






field name 




integer 


len 




char 




chars 




* * 








char 







Field Description: 

len 

Length of the argument. 



PGM $ARGV 



PGM $ARGV PTR 



PGM $CONNV 



chars 

The text of the argument, a character array of 

up to 128 elements. 

A 128-element array of 4-byte integers. An array of 
pointers to returned arguments. 

A 4-byte integer. The address of a returned 
argument. 

A 128-element array of 2-byte integers. An array of 
stream IDs. 



PGM $EC KEY 



A 2-byte integer. Key specifying process 
eventcount. One of the following predefined values: 



PGM $MODE 



PGM $NAME 



PGM_$CHILD_PROC 
Currently the only valid key. 

A 2-byte integer. Specifies the mode in which to 
invoke a program. Any combination of the 
following predefined values: 

An array of up to 128 characters. The text of a 
retrieved argument. 
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PGM DATA TYPES 



PGM $OPTS 



A 2-byte integer. Options for the mode in which to 
invoke a program. One of the following predefined 
values: 



PGM_$WAIT 

Specifies synchronous operation of the invoked 

program. 

PGM_ $BACKGROUND 

Specifies parallel operation of the invoked 

process. 



PGM $PROC 



Process handle record. The diagram below 
illustrates the PGM_$PROC data type: 



predefined 
type 



univ_ptr 



byte: 
offset 



0: 



31 



field name 



integer 



\ / 



Field Description: 



The process pointer. 
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STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



^ 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 ■ 

23). 



UID $T 



code 

A signed number that identifies the type of error 

that occurred (bits - 15). 

A type UID. The diagram below illustrates the 
UID_$T data type: 
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predefined 
record 



byte: 
offset 



0: 
4: 



integer 



integer 



field name 

high 
low 



Field Description: 

high 

The high four bytes of the UK). 

high 

The low four bytes of the UK). 



PGM 
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PGM_$DEL_ARG 

PGM_$DEL_ARG 

Deletes a command line argument. 

FORMAT 

PGM_$DEL_ARG (arg-number) 

INPUT PARAMETERS 

arg-number 

Number indicating the argument to delete. This is a 2-byte integer. 

USAGE 

PGM_$DEL_ARG deletes the specified argument from the argument vector whose 

O address is returned by PGM_GET_ARGS. After execution of PGM_$DEL_ARGS, the 

previously returned address refers to the newly changed argument vector. 

Arguments in the argument vector are numbered through n, where is the program 
name, and n is the final argument. Because PGM_$DEL_ARGS changes the argument 
vector, arguments following deleted arguments change in number. For example, say the 
argument vector contains six arguments (including the program name). After you delete 
the third argument, arguments 4, 5, and 6 must be referenced as arguments 3, 4, and 5. 



O 
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PGM_$EXIT 

Exits from a program to its caller. 

FORMAT 

PGM_$EXIT 

USAGE 

PGM_$EXIT can be used to exit from a program at any point and return to the program's 
caller. 

PGM_$EXIT differs from a simple exit (for example, via FORTRAN'S END statement) in 
that PGM_$EXIT is valid in a subroutine. Execution in a subroutine terminates the main 
program. FORTRAN'S STOP statement, which can be used in main programs and 
subprograms, calls PGM_$EXIT. 

When PGM_$EXIT is executed, any files left open by the program are closed, any storage 
acquired is released, and the inhibit count is reset to its value when the program was 
invoked. 

PGM_$EXIT calls PFM_$SIGNAL with a status code equal to the last severity level set 
by a call to PGM _$SET_ SEVERITY. If no P GM_$ SET _ SEVERITY calls have been 
made, the status code is PGM_$OK. PFM_$ SIGNAL signals this severity to any 
established clean-up handlers, which normally execute in response to any status code other 
than PFM_$CLEANUP_SET. Therefore, any established clean-up routines are normally 
executed after PGM $EXIT is called. 
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PGM_$GET_ARG 

PGM_$GET_ARG 

Returns one argument from the command line. 

FORMAT 

arg-length = PGM_$GET_ARG (arg-number, argument, status, maxlen) 

RETURN VALUE 

arg-length 

Length, in bytes, of the returned argument. This is a 2-byte integer. 

INPUT PARAMETERS 

arg-number 

Number of the argument to return. This is a 2-byte integer. 

OUTPUT PARAMETERS 

argument 

String of length arg-length, containing the requested argument, in PGM_$NAME format. 
This is an array of up to 128 characters. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PGM 
Data Types section for more information. 

INPUT PARAMETERS 

maxlen 

Maximum length of the argument, in bytes. This is a 2-byte integer. 

FORTRAN automatically passes the length of a character string following the string itself. 
Therefore, to return a character string argument to a FORTRAN program, omit the 
maxlen parameter. Use the following format for the call: 

arg-length = PGM_$GET_ARG (arg-number, argument, status) 

This format applies to character strings only. For an argument of any other type, use the 
standard call. 

If the value of maxlen is less than the returned argument length, the program manager 
truncates the returned argument to maxlen bytes and returns the status 
PGM $ARG TOO BIG. 



PGM-9 PGM 



PGM_$GET_ARG 

USAGE ^-^ 

PGM_$GET_ARG returns one argument from the program's caller. The argument is in \ y 

character string format. 

Argument numbers on the command line range from to n. Argument is the program 
name. 



V „■ 
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PGM_$GET_ARGS 

PGM_$GET_ARGS 

Returns the address of the argument vector. 

FORMAT 

PGM_$GET_ARGS (argument-count, arg-vector-addr) 

OUTPUT PARAMETERS 

argument- count 

Number of arguments in the argument vector. This is a 2-byte integer. 

arg- vector- addr 

Pointer to an argument vector; that is, an array of up to 128 pointers to PGM_$ARG. 

USAGE 

PGM_$GET_ARGS returns the address of the argument vector. 

The argument vector is an array of addresses pointing to the arguments. This array can be 
up to 128 elements. 

The addresses are in PGM_$ARGV format. This is a 4-byte integer. See the PGM Data 
Types section for more information. 
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PGM_$GET_EC 

Gets an eventcount to wait for completion of a child process. 

FORMAT 

PGM_$GET_EC (process-handle, process-key, eventcount-pointer, status) 

INPUT PARAMETERS 

process-handle 

Process handle of the child process for which to wait, in PGM_$PROC format. This data 
type is 4 bytes long. See the PGM Data Types section for more information. 

The process handle is returned by PGM_$INVOKE when you create a process. Note that 
the process handle is valid only when you invoke the program in default mode. 

process-key 

Key specifying which process eventcount the system should return, in PGM_$EC_KEY 
format. This is a 2-byte integer. 

Currently the only allowable value is PGM_$CHILD_PROC. 

OUTPUT PARAMETERS 

event count- p oint er 

The eventcount address to be obtained, in E02_$PTR_T format. This is a 4-byte 
integer. 

EC2_$PTR_T is a pointer to an EC2_$EVENTCOUNT_T record. See the EC2 Data 
Types section for more information. 

status 

Completion status, in STATUS_$T format. This data type is 4 bytes long. See the PGM 
Data Types section for more information. 

USAGE 

PGM_$GET_EC returns a pointer to an eventcount that advances when a child process 
terminates. This eventcount address can be passed to EC2_$WAIT to wait for a specific 
child process to complete. You identify the child process by passing the process handle as 
an input parameter. 

When a child process is created, the process eventcount value is 0. When a child process 
terminates, the process eventcount value is 1. To wait on a specific child process, you 
might use: 

PGM_$PROC_EC (....gets process event count ....) 
EC2_$WAIT (. . . .waits until eventcount is 1 . . . .) 

See the Managing Programs Chapter of the Programming With General System Calls 
manual for more information. 
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PGM_$GET_PUID 

PGM_$GET_PUID 

Gets the process UED of a process. 

FORMAT 

PGM_$GET_PUID (process-handle, puid, status) 

INPUT PARAMETERS 

process- handle 

Process handle of the child process for which you want a UID, in PGM_$PROC format. 
This data type is 4 bytes long. See the PGM Data Types section for more information. 

The process handle is returned by PGM_$INVOKE when you create a process. Note that 
the process handle is valid only when you invoke the program in default mode. 

OUTPUT PARAMETERS 

puid 

Process UID, in UID_$T format. This data type is 8 bytes long. See the PGM Data Types 
section for more information. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PGM 
Data Types section for more information. 

USAGE 

PGM_$GET_PUID, which returns the process UID of a child process. 

PGM_$GET_PUID, which is used in conjunction with other system calls. These calls are: 

• PROC2_$GET_INFO, which returns information about a process given a 
PUID. 

• PROC2_$LIST, which returns a list of the PUIDs of all active user processes. 

• PGM_$MAKE_ ORPHAN, which returns the PUID of the orphaned process. 
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PGM_$INVOKE 

Invokes a program. 

FORMAT 

PGM_$INVOKE (pathname, namelength, arg-count, arg-vector, stream-count, 
connection-vector, mode, process-handle, status) 

INPUT PARAMETERS 

pathname 

Pathname of the program to invoke, in NAME _ $PNAME _ T format. This is an array of 
up to 256 characters. 

The specified pathname must be an absolute pathname; the Shell's search rules do not 
apply. 

namelength 

Length of the pathname, in bytes. This is a 2-byte integer. 

arg-count 

Number of arguments to pass to the invoked program. This is a 2-byte integer. 

This number corresponds to the number of elements in the argument vector. 

arg-vector 

Array containing the addresses of the arguments to pass to the invoked program, in 
PGM_$ARGV format. This is an array of 4-byte integers. 

A program can pass any number of arguments to a program it is invoking. Each argument 
must be preceded by a 2-byte integer indicating the number of bytes in the argument. The 
first argument must be the name of the program; the simple name, not the absolute 
pathname (that is, date, not //desperado/com/date). Note that if the invoked program 
calls PGM_$DEL_ARG, the argument vector changes. See the description of 
PGM_$DEL_ARG for details. 

stream- count 

Number of streams to pass to the invoked program. This is a 2-byte integer. 

You are permitted to pass up to 32 streams. In the invoked program these streams are 
numbered to 31. 

connection- vector 

Array containing stream IDs to pass to the invoked program, in PGM_$CONNV format. 
Each stream ID is a 2-byte integer, in STREAM_$ID__T format. Up to 128 elements are 
permitted. 

By default, every program is invoked with four streams, numbered through 3. Stream 
is standard input, stream 1 is standard output, Stream 2 is error input, stream 3 is error 
output. 

Stream IDs refer to objects already opened by the calling program, using 

STREAM $CREATE or STREAM $OPEN. The first element in the connection-vector 
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PGM_$INVOKE 

array becomes stream in the invoked program, the second element becomes stream 1, and 
so on. 

You may leave "holes" in the connection vector by setting a stream ID equal to the 
predefined constant STREAM_$NO_ STREAM. 

mode 

Mode in which to invoke the program, in PGM_$MODE format. This is a 2-byte integer. 
Specify a null set, or one of the following predefined values: 

PGM_$WAIT The program executes as a separate program within the same process as 
the invoking program. 

PGM _ $BACK _ GROUND 

The program executes as a separate process that runs to termination 
independently of the invoking process. 

If you pass a null set (default), the program executes as a separate process that 
communicates its termination status to the invoking program. To specify a null set in C 
and FORTRAN, declare the variable and initialize it to 0. 

OUTPUT PARAMETERS 

process-handle 

Process handle of the process in which the invoked program runs, in PGM_$PROC 
format. This data type is 4 bytes long. See the PGM Data Types section for more 
information. 

The process handle is used as an input parameter in the PGM_$GET_EC, 
PGM_$PROC_WAIT, PGM_$GET_PUID, and PGM_$MAKE_ ORPHAN calls to 
identify an invoked program. 

Note that the process handle is valid only after creating a process in default mode. You 
will get an error (for example, 'reference to illegal address') if you attempt to use the 
process handle of a process created in background mode. The following calls use the process 
handle: PGM_$GET_EC, PGM_$GET_PUID, PGM_$MAKE_ ORPHAN or 
PGM _$PROC_ WAIT. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PGM 
Data Types section for more information. 

Possible values are: 

STATUS _$OK Success status. 

PGM_ $BAD _ CONNV 

Stream vector too large (>32). 

Severity level values returned by the program: 
PGM_$TRUE Value of tested condition is true. 

PGM $FALSE Value of tested condition is false. 
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PGM_$WARNING 

Unusual, but not fatal condition detected. 

PGM_$ERROR Syntactic or semantic errors in input; output is structurally sound. 

P GM _ $INVALK> _ OUTPUT 

Syntactic or semantic errors in input; output is not structurally sound. 

PGM_ $INTERNAL _FATAL 

Internal fatal error detected. 

Any status returned by the invoked program. 

Any status returned by modules that PGM_$INVOKE calls. 



USAGE 



v_... 



PGM_$INVOKE invokes a program in the specified mode, and passes that program any ( 

parameters that it needs. The addresses of arguments are passed to the invoked program V_v 

by way of the arg-vector, which is an array of those addresses. The invoked program uses 
the system routines, PGM_$GET_ARGS, PGM_$GET_ARG, and PGM_$DEL_ARG 
to access the arguments. See the documentation of those routines for details. 

You can change standard input for the invoked program by opening the desired input file 
and passing its stream ID as the first element of the connection vector. The same is true for 
standard output, standard error input, and standard error output. 

When the invoked program finishes executing, files it has opened are closed, storage it has V_, 

acquired is released, and the inhibit count is the same as it was upon entry. 

The behavior of an invoked program differs depending on the mode in which the program is 
invoked. 



Invoking a Program in Wait Mode 



When you invoke a program this way, the invoking program executes the program and 
waits for it to complete before continuing. 

A program invoked in wait mode calls PGM_$SET_ SEVERITY to indicate its completion 
status to the invoking program. 

A program ends when one of the following takes place: 

• A language defined termination statement is executed 

• An unhandled fault occurs 

• You call PGM $EXIT 
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Normal termination returns execution to the calling program. An unhandled error either 
terminates the program with an error status or invokes a clean-up handler. PGM_$EXIT 
invokes any established clean-up handlers, then exits to the calling program. Any severity 
levels set during program execution are returned in the status parameter. 



Invoking a Program in Default Mode 



When you invoke a program specifying a null set, the invoking program creates a new 
process in which to run the program. The invoking process may wait for the child process 
to complete and determine its termination status by calling PGM_$PROC_WAIT. 

When a process invokes another process, the invoking process is referred to as the parent 
process and the invoked process is referred to as the child process. Executing a program in 
a child process is useful if you wish to perform concurrent processing or if your program 
requires a large amount of address space. 



Waiting for a Child Process 

The PGM_$GET_EC call permits you to get a process eventcount that is advanced when 
a specified process terminates. By using this call in conjunction with the system calls 
EC2_$READ and EC2_$WAIT, a parent process can wait for the completion of a child 
process (or a list of event counts). 



Getting the Completion Status of a Child Process 



Once a child process has completed, examine its completion status. To obtain the 
completion status of a default mode process, call PGM_$PROC_WAIT in the parent 
process. PGM _$PROC_ WAIT takes the process handle of the invoked program as an 
input parameter and returns its completion status. If the child process has not completed 
execution at the time of the PROC_WAIT call, execution of the parent process suspends 
until a completion status is available. 

A certain amount of resources in a parent process are used to keep track of a child process. 
When a call to PGM_$PROC_WAIT is completed those resources are released. If you 
invoke a number of child processes without ever calling PROC_WAIT, the parent process 
may run out of resources. If you are not interested in the completion status of the invoked 
program, invoke it using background mode. 
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Invoking a Program in Background Mode 



When you invoke a program specifying PGM _$BACK_ GROUND, the invoking program 
creates a new process in which to run the program. Background mode differs from default 
mode in that a background mode process runs completely independently of the parent. 
That is, there is no communication of the completion status. 

Background mode is useful for performing processing that has no further dependence on the 
parent process. For example, a parent process may perform interactive data collection, 
invoke a program in a background process to manipulate the data, and then return to 
further data collection. This permits you to collect and manipulate the data concurrently. 

Because a background mode process has no dependence on the parent, it is referred to as an 
orphan process. You can change a default child process into an orphan process by calling 
PGM_$MAKE_ORPHAN. 

Note that the process handle is valid only after creating a process in default mode. You 
will get an error (for example, 'reference to illegal address') if you attempt to use the 
process handle of a process created in background mode. The following calls use the process 
handle: PGM_$GET_EC, PGM_$GET_PUID, PGM_$MAKE_ ORPHAN or 
PGM $PROC WAIT. 
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PGM_ $MAKE_ ORPHAN 

Changes a normal child process into an orphan process. 

FORMAT 

PGM_$MAKE_ORPHAN (process-handle, puid, status) 

INPUT PARAMETERS 

process- handle 

Process handle of the child process to orphan, in PGM_$PROC format. This data type is 
4 bytes long. See the PGM Data Types section for more information. 

The process handle is returned by PGM_$INVOKE when you create a process. Note that 
the process handle is valid only when you invoke the program in default mode. 

OUTPUT PARAMETERS 

puid 

Process UID, in UID_$T format. This data type is 8 bytes long. See the PGM Data Types 
section for more information. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the PGM 
Data Types section for more information. 

USAGE 

PGM_$MAKE_ ORPHAN changes the specified child process into an orphan process. 

An orphan process is one that is run in PGM_$BACKGROUND mode. An orphan process 
runs independently of the parent process and no termination status is returned to the 
parent. 
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PGM_$PROC_WAIT 

Waits for a process that has been created with PGM_$INVOKE to terminate and returns 
a completion status for the process. 

FORMAT 

PGM_$PROC_WAIT (process-handle, status) 

INPUT PARAMETERS 

process-handle 

Process handle of the child process for which to wait, in PGM_$PROC format. This data 
type is 4 bytes long. See the PGM Data Types section for more information. 

The process handle is returned by PGM_$INVOKE when you create a process. Note that 
the process handle is valid only when you invoke the program in default mode. 

OUTPUT PARAMETERS 

status 

The child process completion status, in STATUS _$T format. This data type is 4 bytes 
long. See the PGM Data Types section for more information. 

USAGE 

PGM_$PROC_WAIT suspends the execution of a parent process until the completion of a 
specified child process. This call permits a child process to pass a completion status to the 
parent upon termination. 

Using PGM_ INVOKE in default mode (the empty set) and then calling 
PGM_$PROC_WAIT is equivalent to using PGM_$INVOKE in PGM_$WAIT mode. 
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PGM_ $SET_ SEVERITY 

Sets the severity level for a program. 

FORMAT 

PGM_$SET_SEVERITY (severity-level) 

INPUT PARAMETERS 

severity- level 

The severity level returned to the caller. This is a 2-byte integer. Specify only one of the 
following predefined values: 

PGM_$OK The program completed successfully and performed the requested action. 

PGM_$TRUE The program completed successfully; its purpose was to test a condition, 
and the value of that condition was TRUE. 

PGM_$FALSE The program completely successfully; its purpose was to test a condition, 
and the value of that condition was FALSE. 

PGM_$WARNING 

The program completed successfully and performed the requested action. 
However, an unusual (but nonfatal) condition was detected. 

PGM_$ERROR The program could not perform the requested action because of syntactic 
or semantic errors in the input. The output is structurally sound, 
however. 

PGM _ $OUTPUT _ INVALID 

The program could not perform the requested action because of syntactic 
or semantic errors in the input, and the output is not structurally sound. 

PGM_ $INTERNAL _FATAL 

The program detected an internal fatal error and ceased processing. The 
state of the output is neither defined nor guaranteed. 

PGM_ $PROGRAM_FAULTED 

The program detected and handled a fault. 

Severity levels are a subset of the general system status codes. 

USAGE 

Every program returns a severity level to its caller. By default, the severity level is 
PGM_$OK. Use PGM _$SET_ SEVERITY in the invoked program to change the level to 
another value. 

C programmers wishing to use this call must specify the -entry option to /com/bind (in the 
UNIX environment)or the -e option to /bin/Id (in our operating system) to specify the start 
routine manually (normally "main"). The alternative to PGM _$SET_ SEVERITY is to 
use the exit()~ or returnQ— routine to return a program status. 
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The following are examples of appropriate changes to the severity level. 

PGM_$TRUE or PGM_$FALSE would be returned by an "equal" program that 
compares its two arguments to see if they are equal. 

PGM_$WARNING would be returned by DLF (DELETE_FILE) if the file to be deleted 
did not exist. 

PGM_$ERROR would be returned by a compiler if the input program contained an error 
that prevented a correct translation, but the output object module format was correct. 

PGM_$ OUTPUT _ INVALID would be returned by a compiler if an error in the input 
program caused the object module format to be invalid. 

PGM_$INTERNAL_ FATAL would be returned if the program could not proceed because 
it detected that its data structures were corrupted. 

PGM_$PROGRAM_FAULTED would be returned if the program signaled a fault and 
wishes to inform the invoking program without resignalling the fault. 



PGM PGM-22 



o 



o 



o 



PGM ERRORS 



ERRORS 

STATUS _$OK 

Successful completion. 

PGM_$ERROR 

The program could not perform the requested action because of syntactic or semantic 
errors in the input. The output is structurally sound, however. 

PGM_$FALSE 

The program completely successfully; its purpose was to test a condition, and the 
value of that condition was FALSE. 

PGM_$INTERNAL_FATAL 

The program detected an internal fatal error and ceased processing. The state of the 
output is neither defined nor guaranteed. 

PGM_$OK 

The program completed successfully and performed the requested action. 

PGM_$OUTPUT_INVALID 

The program could not perform the requested action because of syntactic or semantic 
errors in the input, and the output is not structurally sound. 

PGM_ $PROGRAM_FAULTE 
The program faulted. 

PGM_$TRUE 

The program completed successfully; its purpose was to test a condition, and the value 
of that condition was TRUE. 

PGM_$WARNING 

The program completed successfully and performed the requested action. However, an 
unusual (but non- fatal) condition was detected. 
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The PM (Process Manager) programming calls create and delete processes. This section describes 
their data types and call syntax. The PM calls do not use produce unique error messages. Refer 
to the Introduction at the beginning of this manual for a description of data-type diagrams and 
call syntax format. 
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CONSTANTS 



NAME $PNAMLEN MAX 



256 Maximum length of a pathname. 



DATA TYPES 



NAME $PNAME T 



STATUS $T 



An array of up to NAME _$PNAMLEN_ MAX 
(256) characters. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 
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Field Description: 

all 

All 32 bits in the status code. 



V 



fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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PM_$GET_HOME_TXT 

PM_$GET_HOME_TXT 

Returns the home directory of the calling process as a string. 

FORMAT 

PM_$GET_HOME_TXT (maxlen, home, len) 

INPUT PARAMETERS 

maxlen 

Maximum number of characters to be returned (at most, the size of the buffer you assign 
for home). This is a 2-byte positive integer. This parameter need not exceed 256. 

OUTPUT PARAMETERS 

home 

Pathname of the home directory for the SID (log-in identifier) of this process. This is an 
array of up to 256 characters. 

len 

Number of characters returned in the home parameter. This is a 2-byte positive integer. 

USAGE 

The home directory is obtained from the network registry when you log in and is inherited 
by all your processes. 
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PM_ $GET _ SID _ TXT 

Returns the SID (log-in identifier) of the calling process as a string. 

FORMAT 

PM_$GET_SID_TXT (maxlen, sid, len) 

INPUT PARAMETERS 

maxlen 

Maximum number of characters to be returned (at most, the size of the buffer you assign 
for home). This is a 2-byte positive integer. This parameter need not exceed 140. 

OUTPUT PARAMETERS 

sid 

String containing the person, project, organization and node ID of the SID (log-in identifier) 
of this process, in the form: 

person . group . proj ect . nodeid 
This is an array of up to 140 characters. 

len 

Number of characters returned in the log-in identifier. This is a 2-byte positive integer. 

USAGE 

Your SID is the full identifier obtained from the network registry when you log in and is 
inherited by all your processes. 
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The PRF (Print Library) programming calls provide application control of the print queue and 
the PRF options. This section describes their data types, call syntax, and error codes. Refer to 
the Introduction at the beginning of this manual for a description of data-type diagrams and call 
syntax format. 
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DATA TYPES 



NUM VAR T 



A print option expressed as a numeric value. The 
diagram below illustrates the NUM_VAR_T data 
type: 
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Field Description: 

real32 

A 32-bit real number. 

int32 

A positive 31-bit number. 

pad_intl6 
Padding. 

intl6 

A positive 16-bit number. 

pad_intl6_n 
Padding. 
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intl6_n 

A positive or negative 16-bit number. 

pad _ byte 
Padding. 



STATUS $T 



int8 

A positive 8-bit integer. 

intl 

A boolean (bit 0). 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



o 



byte: 
offset 



31 



field name 



0: 


integer 


all 


0: 


l 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



o 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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UNIV_PTR A 4-byte integer. A pointer to allocated storage. 
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PRF_$CONFIG_FILE 

Sets the print options in the print request packet from a configuration file. 

FORMAT 

PRF_$CONFIG_FILE (name, name-length, status) 

INPUT PARAMETERS 

name 

The full pathname of the configuration file from which the print options are to be read. 
This an array of up to 256 characters. 

name- length 

The number of characters in the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the PRF 
Data Types section for more information. 

USAGE 

This procedure allows you to specify print options in a configuration file. The options are 
then read from the file into a print request packet. For a list of available options, refer to 
the description of the PRF _$SET_ OPTION call. The configuration file is formatted as 
in the following sample: 

COPIES 1 
MARGINS ON 
PLOT ON 
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PRF _ $DELETE _ ENTRY 

Deletes a print request from the print queue. 

FORMAT 

PRF_$DELETE_ENTRY (queue-entry-name, queue-entry-name-length, status) 

INPUT PARAMETERS 

queue- entry- name 

The full pathname of the print request packet. This an array of up to 256 characters. 

queue- entry-name- length 

The number of characters in the pathname of the print request packet. This is a 2-byte 
integer. 

OUTPUT PARAMETERS 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the PRF 
Data Types section for more information. 

USAGE 

This procedure takes as input the print request packet name returned by 

PRF _$STREAM_ PRINT, PRF _$NAME_ PRINT, and PRF _$ QUEUE _ PRINT and 

deletes the print request packet from the /sys/print/ queue directory. 

You should take care when making this call that you do not unintentionally delete your 
data file. If the delete option (refer to the list of options in the description of 
PRF _$SET_ OPTION) is ON, PRF _$DELETE_ ENTRY will also delete the data file. 
Thus, if you are using this call in conjunction with PRF _$ QUEUE _ FILE, you will 
probably want to set the delete option to OFF since the PRF _$ QUEUE _ FILE does not 
create additional copies of the data file. 
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PRF_$INIT 

PRF_$INIT 

Sets print request packet options to default values. 

FORMAT 

PRF_$INIT (stream-id. status) 

INPUT PARAMETERS 

stream- id 

The stream to write error and status messages to, in STREAM_$ID__T format. This is a 
2-byte integer. See the STREAM Data Types section for more information. 

OUTPUT PARAMETERS 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the PRF 
Data Types section for more information. 

USAGE 

This procedure sets the print request packet options to their default values and sets the 
stream to be used for sending error and status information. 
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PRF_$INQ_ OPTION 



Returns the string and number representations of the print request packet option to the 
caller. 



FORMAT 

PRF_$INQ_OPTION (option, option-length, number-value, string, -value, 
string-length, status) 

INPUT/OUTPUT PARAMETERS 

option 

Specifies the option to be used when printing the data. Refer to the description of the 
PRF_$SET_ OPTION for a list of available options. 

option- length 

The number of characters in the specified option. 

OUTPUT PARAMETERS 

number-value 

The numerical representation of the value of the option, in NUM_VAR_T FORMAT. See 
the PRF Data Types section for more information. 

string-value 

The string representation of the value of the option. This an array of up to 256 characters. 

string- length 

The number of characters in the string-value. This is a 2-byte integer. 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the PRF 
Data Types section for more information. 

USAGE 

This procedure returns to the caller the value (in string and number representation) of an 
option. 
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PRF_ $NAME_PRINT 

PRF_$NAME_PRINT 

Copies a data file to the /sys/print/spooler directory and generates print request packet. 

FORMAT 

PRF_$NAME_PRINT (filename, filename-length, queue-name, 
queue-name-length, status) 

INPUT PARAMETERS 

filename 

The full pathname of the data file. This an array of up to 256 characters. 

filename- length 

The number of characters in the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

queue-name 

The full pathname of the print request packet. This an array of up to 256 characters. 

queue- name- length 

The number of characters in the pathname of the print request packet. This is a 2-byte 
integer. 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the PRF 
Data Types section for more information. 

USAGE 

This procedure copies the data file to the /sys/print/spooler directory and then generates a 
print request packet that contains the options describing how the file is to be printed. 
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PRF_$QUEUE_FILE 

Generates a print request packet in the /sys/print/queue directory. 

FORMAT 

PRF_$QUEUE_FILE (filename, filename-length, queue-name, queue-name-length, 
status) 

INPUT PARAMETERS 

filename 

The full pathname of the data file. This an array of up to 256 characters. 

filename- length 

The number of characters in the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

queue-name 

The full pathname of the print request packet. This an array of up to 256 characters. 

queue- name- length 

The number of characters in the pathname of the print request packet. This is a 2-byte 
integer. 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the PRF 
Data Types section for more information. 

USAGE 

This procedure generates a print request packet that contains" the parameters describing 
how the file is to be printed. Note that the data file specified as an input parameter is not 
copied to the /sys/print/spooler directory and will therefore be deleted after it has been 
printed unless you set the delete option to OFF (refer to the list of print options in the 
description of PRF _$SET_ OPTION). 
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PRF_$SET_OPTION 

PRF _ $SET _ OPTION 

Sets an option in the print request packet. 

FORMAT 

PRF_$SET_OPTION (option, option-length, number-value, 
string-value, string-length, status) 

INPUT PARAMETERS 

option 

Specifies the option to be used when printing the data. A description of the available 
options appears below under "USAGE". 

option- length 

The number of characters in the specified option. 

number-value 

The numerical representation of the value of the option, in NUM_VAR_T FORMAT. See 
the PRF Data Types section for more information. 

string-value 

The string representation of the value of the option. This an array of up to 256 characters. 

string- length 

The number of characters in the string-value. This is a 2-byte integer. 

string- encoding 

Indicates whether the value of the option is encoded as a string or number. This is a 
boolean value. If true, the option is encoded as a string; if false, a number. 

OUTPUT PARAMETERS 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the PRF 
Data Types section for more information. 

USAGE 

This procedure sets a specified print option in the print request packet. The print server 
(PRSVR) uses the option to determine how to print the data. Following are the options 
that you can specify: 

SEA[RCH_DIR] ON|OFF 

Search through all the directories of all the active processes on 
your node for the file(s) to be printed. This option is most useful 
.in interactive mode, when the working directory of the process 
may be different from the working directory of the file to be 
printed. The default state is OFF. 

D[ELETE] ON|OFF 

Delete the data file after it has been printed. The default state is 
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on; i.e., if you do not specify this option, the print server 
(PRSVR) deletes the data file after it has been printed. 

COP[IES] n 

Print n copies of the file. If COP[IES] is specified, "n" is 
required. If this option is omitted altogether, one copy is printed 
by default. 

PR [INTER] name 

Specify the name of the printer that is to print the data file. This 
option is useful only if more than one printer is in use on the 
network. If you omit this option, the print server (PRSVR) uses 
the default printer name "P". 

S[ITE] entry _dir 

Specify print queue (/SYS/PRINT) on an alternate node by 
giving that node's entry directory name. This option allows you 
to maintain more than one print queue directory. You may want 
to maintain separate queues for different organizations, or you 
may want two queues to provide redundancy in case of node 
failure. 

USER [_ NAME] name 

Specify the user name that will appear on the banner page of the 
printed file. The print server alarm facility also uses this name 
to determine who should be notified when printing is complete 
(see SIG below). This means that this name must be a valid 
login name (unless you don't care about sending an alarm). If 
you omit this option, the current login name is used. 

SIG[NAL] ALARM | OFF 

Request an alarm server signal when the file has finished 
printing. The default state is OFF. 

BAN[NER] ON|OFF 

Enable/disable banner page. The default is specified in the print 
server configuration file. 

CONFIG [_ FILE] [pathname] 

Specify a file containing print request packet options, one per 
line. Refer to the description of the PRF _$ CONFIG _ FILE call 
for information concerning the format of the configuration file. 
If you omit the pathname, the print server executes the 
configuration file ~USER_DATA/PRF.DB. 

PAPER_SIZE A|B|LEGAL|A3|A4|A5|B4|B5 

Specify the page size to use on the LASER26 printer. If you omit 
this option, the default is the page size as specified in the print 
server configuration file. 

ORIENT[ATION] P ORT [TRAIT] |LAND [SCAPE] 

Print the file according to the specified orientation. Portrait 
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specifies that text lines or the x axis of bitmaps will be parallel to 
the short edge of a page. Landscape specifies that text lines or 
the x axis of bitmaps will be perpendicular to the short leading 
edge. This option applies only to printers that include the 
PostScript interpreter (i.e., LASER26, LaserWriter, Genicom, and 
V80 printers with the PostScript decomposer software). If you 
omit this option, the default state is portrait. Specifiying this 
option will override any auto-rotation performed on bitmaps. 

TEXT Specify text mode for printing ASCII files. This is the default 
print mode. 

PLOT ON|OFF 

Specify plot mode. Include this option to print bitmap files 
created by a graphics metafile (GMF) manager or GPR or the 
CPSCR (COPY_SCREEN) command. Turning PLOT off forces 
text mode. 

TRANSPARENT ON|OFF 

Specify that when the file is printed, the records of the file are 
passed directly to the printer driver routine with no processing by 
the print server. Turning TRANSPARENT off forces text mode. 

POSTSCRIPT] ON|OFF 

Specify that the printer uses a software PostScript interpreter; 
i.e., the specified printer is driven and licensed to run the print 
server (prsvr_post) that contains a software version of the 
PostScript interpreter. If you specify OFF for this option, data 
is printed as text, plot, or transparent data. If ON, data is 
passed through the PostScript interpreter, as though the printer 
were an Apple LaaserWriter or LASER26 printer. This option 
allows you to take full advantage of the PostScript language 
when printing text or bitmaps, or bypass the interpreter for 
higher throughput. The default state is off. 

The following options apply to text files only: 

MARGINS ON|OFF 

Enable/disable the margin settings specified by the next four 
options. The default state is on; i.e., if you do not specify this 
option, the margin settings are those you have specified with the 
next four options. 

TOP n Specify page top margin, in n (a real number) inches. The 

default is a value specified in the print server configuration file. 

BOT[TOM] n 

Specify page bottom margin, in n (a real number) inches. The 
default is a value specified in the print server configuration file. 

RIGHT n 

Specify page right margin, in n (a real number) inches. The 
default is inches. 
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LEFTn 

Specify page left margin, in n (a real number) inches. The 
default is inches. 

HEADERS ON|OFF 

Enable/disable page headers and footers as specified by the next 
two options. If you omit the next two options, the default is as 
specified in the print server configuration file. 

HEAD[_ STRING] 1-string/c-string/r-string 

Specify the contents of left, center, and right components of the 
page header generated by print server. Components may be 
empty strings. The following special characters return the values 
indicated when they appear in the header strings: 

@ = Escape character 

# = Current page number with 1 leading and 1 trailing space 

% = Current date 

! = Filename 

& = Filename's last time, date modified 

Insert a space in text string (literal spaces are not allowed) 



* _ 



Example: HEAD !/Page#/% will produce a header with the 
filename in the left component, the string "Page" followed by the 
current page number in the center component, and the current 
date in the right component. The default header is a string 
specified in the print server configuration file. 

FOOT[_ STRING] 1-string/c-string/r-string 

Specify contents of page footers. The format is the same as for 
HEAD above. There is no default footer (null string). 

FTN ON|OFF 

Cause the print server to use FORTRAN forms control even if 
the file does not have the FORTRAN carriage control flag. Use 
of this option causes print server to interpret the first character 
of each line as a FORTRAN carriage control character (and not 
print it). This can be unfortunate if the file has ASCII carriage 
control, so be careful. The default state is OFF. 

WRAP ON|OFF 

Enable/disable automatic line wrapping. When enabled, the 
print server wraps any lines that exceed the right margin onto 
the next line. When disabled, the print server truncates lines 
that exceed the right margin. 



r n. 
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COL[UMNS] 1|2 

Specify that text will be printed in one or two columns. 
Currently restricted to use with LASER26, APPLE 
LASERWRITER, and printers that contain the PostScript 
interpreter. The default is one column. 

The following options are for use with printers supporting 
variable font and pitch sizes: 

LPI n Specify the line spacing in lines per inch. The default is six lines 
per inch. 

PITCH n 

Set the pitch (characters/inch) setting for printing the data file. 
The following pitch settings are available on the indicated 
printers: 



Printronix: 10 

Spinwriter: 12 

Imagen: 8.5, 10, 12, 15, 17.1 

GE: 9.6, 10, 10.6, 11.1, 12, 13.1, 13.8, 15, 16.7, 18 

Versatec 12 



POINT n 

Set the point size for the font to be used. This is a real number in 
units of a point (1/72 inch). PostScript printers will accept any 
size from 1 to 100. Other printers are limited to the pitch sizes 
specified with the PITCH option. 

WEIGHT light|medium|bold 

Set the weight of the font to be used. This option is only valid 
for the GE printer type. The default is 'medium'. 

LQ ON|OFF 

Specify that the document is to be printed in 'letter quality' (ON) 
as opposed to 'draft' (OFF) mode. This option is only valid for 
the GE printer type. The default state is OFF. 

The following options apply to plot files: 

RESOLUTION] n 

Specify resolution of output plot in dots per inch. If you specify 
a resolution not available on the particular printer, the file is 
printed at the closest available resolution. The default resolution 
is specified in the PRSVR configuration file. 



(^J WHITE[_ SPACE] n 
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Specify amount of white space (in inches) to appear between 
multiple plots in one file. The default is three inches. 

BW[_REV] ON|OFF 

Enable/disable black and white reversal for bitmaps. The default 
state is OFF. 

MAGNIFICATION] n 

Specify bitmap magnification value, 'n' is an integer in the range 
-1 to 16. The default is 0. 

-1 : Selects auto-scaling to magnify the bitmap to fill the 
available page space. 

0: Selects "one-to-one" scaling between the display and the 
printer for GMF bitmaps. (For GPR bitmaps, this 
translates to magnification 1.) 

1-16 : Selects magnification by that amount. Portions of the 

magnified bitmap that exceed the printer page boundaries 
are clipped. 
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PRF_$STREAM_PRINT 

PRF _ $STREAM _ PRINT 

Copies data from a stream to the /sys/print/spooler directory and generates a print request 
packet in the /sys/print/queue directory. 

FORMAT 

PRF_$STREAM_PRINT (stream-id, queue-name, name-length, status) 

INPUT PARAMETERS 

stream- id 

The stream id of the data to be printed, in STREAM _$ED_T format. This is a 2-byte 
integer. See the STREAM Data Types section for more information. 

OUTPUT PARAMETERS 

queue- name 

The full pathname of the print request packet. This an array of up to 256 characters. 

name- length 

The number of characters in the pathname. This is a 2-byte integer. 

status 

Completion status in STATUS _$T format. This data type is 4 bytes long. See the PRF 
Data Types section for more information. 

USAGE 

This procedure copies input data to the /sys/print/spooler directory. It then generates a 
print request packet that contains the options describing how the file is to be printed. This 
procedure will print data from the first record in the stream up to the EOF mark. 
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ERRORS 



STATUS _$OK 

Successful completion. 
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The PROC1 (Level 1 Process) programming call returns the CPU time used by a Level 1 process. 
This section describes its data types and call syntax. The PROCl call does not produce unique 
error messages. Refer to the Introduction at the beginning of this manual for a description of 
data-type diagrams and call syntax format. 
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DATA TYPES 



TIME $ CLOCK T 



Internal representation of time. The diagram below 
illustrates the TIME_$CLOCK_T data type: 



predefined 
record 



time $clockh t 



byte: 
offset 



0: 
4: 



integer 



integer 



field name 

high 
low 



Field Description: 



predefined 
record 





high 






High 32 bits of the clock. 




low 




Low 16 bits of the clock. 


byte: 
offset 




field name 


0: 


positive 
integer 




high 16 


2: 


positive integer 


low 32 



v_.'" 



Field Description: 

highl6 

High 16 bits of the clock. 

low32 

Low 32 bits of the clock. 
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PR0C1_$GET_CPUT 

PR0C1 _ $GET_ CPUT 

Returns the CPU time used by this process. 

FORMAT 

PROCl_$GET_CPUT (clock) 

OUTPUT PARAMETERS 

clock 

The amount of CPU time used by this process since its creation, in TIME_$CLOCK_T 
format. This data type is 6 bytes long. See the TIME Data Types section for more 
information. 

USAGE 

PROCl_$GET_CPUT returns the amount of CPU time that the calling process has used 
since its creation. The returned clock value has a resolution of 4 microseconds. 

CPU time is the time during which the process is running in the CPU. This includes the 
time that the operating system is performing services for the process, but does not include 
the time that the process spends waiting for I/O transfers to complete. 
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The PR0C2 (Level 2 Process Manager) programming calls provide information about user 
processes. This section describes their data types, call syntax, and error codes. Refer to the 
Introduction at the beginning of this manual for a description of data-type diagrams and call 
syntax format. 
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DATA TYPES 



PROC2 $INFO T 



Process information record. The diagram below 
illustrates the PROC2_$INFO_T data type: 



predefined 
type 



uid $t 



proc2_$state_t 



time $clockh t 



byte: 
offset 




4 

8 
12 
14 
16 
20 
24 
28 
32 
34 



integer 



integer 



integer 



integer 



integer 



integer 



integer 



integer 



integer 



integer 



integer 



field name 

stack_uid.high 

stack_uid.low 

stack_base 

state 

usr 

upc 

usp 

usb 

cpiMotal.high 

cpu_total.low 

priority 



Field Description: 

stack _ uid 

Uid of user stack. 

stack _ base 

Base address of user stack. 

state 

Process state - ready, waiting, etc. 

usr 

User status register. 

upc 

User program counter. 

usp 

User stack pointer. 

usb 

User stack base pointer (A6). 
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PR0C2 $UID LIST T 



cpu_ total 

Cumulative cpu time used by process. 

priority 
Process priority. 

An array of UIDs (in UID_$T format) of up to 24 
elements. 



PR0C2 $STATE T 



A 2-byte integer. State of a user process. Any 
combination of the following predefined values: 



PROC2_$WAITING 
Process is waiting. 



PR0C2_$SUSPENDED 
Process is suspended. 

PROC2_$SUSP_PENDING 
Process suspension is pending. 



PR0C2_$B0UND 
Process is bound. 
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A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 


31 






field name 



0: 


integer 


all 


0: 


' 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 



O 



fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 3 1 ). 



PROC2-3 



PROC2 



PR0C2 DATA TYPES 



subsys 

The subsystem that encountered the error (bits \ 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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PR0C2 _ $GET _ INFO 

Returns information about a process. 

FORMAT 

PR0C2_$GET_INF0 (process-uid, info, inf o-buf-length, status) 

INPUT PARAMETERS 

process-uid 

The UID of the process for which you want information, in UID_$T format. This data 
type is 8 bytes long. See the PROC2 Data Types section for more information. 

You can get process UIDs by calling PROC2_$WHO_AM_I and PROC2_$LIST. 

If the process-uid in the call is the caller's own process, the only information returned is the 
stack UID and virtual address. If you want to find out the amount of CPU time used by 
the caller's process, use PROCl_$CPU_TIME. 

info- buf- length 

Length of the information buffer allotted for returned information, in bytes. This is 
normally 36 bytes. 

OUTPUT PARAMETERS 

info 

Information about the process, in PROC2_$INFO_T format. This data type is 36 bytes 
long. See the PROC2 Data Types section for more information. 

status 

Completion status, in STATUS_$T format. This data type is 4 bytes long. See the 
PROC2 Data Types section for more information. Possible values are: 

STATUS _$OK Completed successfully. 

PROC2 _ $IS _ CURRENT 

Specified calling process UID (success). 

PROC2_$UID_NOT_FOUND 

Specified UID is not on node. 

USAGE 

GET_$INFO returns information about a process when supplied with a process UID. The 
information returned consists of the following: 

• The program state (ready, waiting, suspended, SUSP _ PENDING, bound). 

• The User Status Register (USR). 

• The User Program Counter (UPC). 
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• The user stack pointer (A7). 

• The stack base pointer (A6). 

• The amount of CPU time used. 

• The CPU scheduling priority. 
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PR0C2_$LIST 

Returns a list of existing level 2 (user) processes in the caller's node. 

FORMAT 

PR0C2_$LIST (uid-list, max-num-uids, number-uids) 

OUTPUT PARAMETERS 

uid-Iist 

The UIDs of the active level 2 processes on the system, in PR0C2_$UID_LIST_T 
format. This is a 24-element array of UIDs. Each UDD is a 4-byte integer in UID_$T 
format. 

INPUT PARAMETERS 

max-num-uids 

Maximum number of process UIDs to be returned. (At most, the size of the buffer you 
assign for uid-list. This is a 2-byte integer. 

OUTPUT PARAMETERS 

number-uids 

Number of active level 2 processes on the node, even if that number is greater than 
max-num-uids. This is a 2-byte integer. 

USAGE 

The UIDs of all level 2 processes (user processes) on the caller's node, up to max-num-uids, 
are returned. 
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PR0C2_$WH0_AM_I 

Returns the UED of the calling process. 

FORMAT 

PR0C2_$WH0_AM_I (my-uid) 

OUTPUT PARAMETERS 

my-uid 

The UID of the calling process, in UID_$T format. This data type is 8 bytes long. See the 
PROC2 Data Types section for more information. 

USAGE 

You can use a UID obtained through this call to find out information about your process 
through the PROC2_$GET_INFO call. 
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ERRORS 

STATUS _$OK 

Successful completion. 

PROC2_$BAD_STACK_BASE 
Bad stack base. 

PROC2 _ $IS _ CURRENT 

Request is for current process. 

PROC2_$NOT_LEVEL_2 

Not a level two process. 

PROC2_$UID_NOT_FOUND 
Process not found. 



o 



o 



o 
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o 



RWS 



The RWS (Read/Write Storage) programming allow programs to allocate "scratch" read/write 
storage. This section describes their data types, call syntax, and error codes. Refer to the 
Introduction at the beginning of this manual for a description of data- type diagrams and call 
syntax format. 
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O 
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RWS DATA TYPES 



DATA TYPES 



RWS $POOL T 



A 2-byte integer. Types of pools from which to 
allocate read/write or heap storage. One of the 
following predefined values: 



RWS_$STD_POOL 

Standard pool makes storage accessible to 

calling process only. 

RWS_$STREAM_TM_POOL 
Stream pool makes storage accessible to 
calling program and to a program invoked 
with the UNIX EXEC system call. 



STATUS $T 



RWS_$GLOBAL_POOL 

Global pool makes storage accessible to all 

processes. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 


31 






field name 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 
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RWS DATA TYPES 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 

UNIV_PTR A 4-byte integer. A pointer to allocated storage. 



O 



o 
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RWS_$ALLOC 

RWS_$ALLOC 

Allocates read/write storage for C, FORTRAN or Pascal programs. 

FORMAT 

RWS_$ALLOC (storage_sz, storage_ptr) 

INPUT PARAMETERS 

storage _sz 

The number of bytes of storage needed. This is a 4-byte integer. 

OUTPUT PARAMETERS 

storage _ptr 

The address of the new storage space, in UNIV_PTR format. This is a 4-byte integer. A 
returned address of zero (NIL) means that RWS_$ALLOC could not allocate the desired 
storage. 

USAGE 

RWS_$ALLOC allocates the specified number of bytes of read/write storage to the calling 
process and returns the address of the storage area. 

This routine is useful for allocating different quantities of dynamic storage, depending on a 
run- time factor. 

FORTRAN programmers: due to FORTRAN calling conventions, this is currently the only 
RWS call you can use to allocate read/write storage. 

Pascal and C programmers can use other RWS calls to allocate read/write or heap 
(releaseable read/write) storage. See the calls, RWS_$ALLOC_RW_POOL and 
RWS_$ALLOC_HEAP_POOL for details. 

C programmers might want to use the C library routine MALLOC to allocate storage. 
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RWS $ALLOC HEAP 



RWS _ $ALLOC _HEAP 

( ) Allocates heap (releaseable read/write) storage for Pascal and C programs. This call is 

obsolete and is documented here for maintenance purposes only. You should replace it 
with RWS_$ALLOC_HEAP_POOL. 

FORMAT 

storage_ptr = RWS_$ALLOC_HEAP (storage_sz) 

RETURN VALUE 

storage _ptr 

The address of the new storage space, in UNIV_PTR format. This is a 4-byte integer. A 
returned address of zero (NIL) means that RWS _$ALLOC_ HEAP could not allocate the 
desired storage. 

INPUT PARAMETERS 

storage _sz 

The number of bytes of storage needed. This is a 4-byte integer. 

USAGE 

Note that RWS_$ALLOC_HEAP_POOL replaces this obsolete call, which we include for 
maintenance purposes only. For current and future development, use 
RWS_$ALLOC_HEAP_POOL. 

RWS _$ALLOC_ HEAP allocates the specified number of bytes of releaseable read/write 
storage to the calling process and returns the address of the storage area. It allocates 
storage from the standard RWS pool, which makes the storage accessible to the calling 
program only. Use RWS _$RELEASE_ HEAP to release storage allocated with this call. 

FORTRAN programmers: due to FORTRAN calling conventions, RWS_$ALLOC is 
currently the only RWS call you can use to allocate read/write storage. 

C programmers might want to use the C library routine MALLOC to allocate storage. 



O 



o 



o 
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RWS_$ALLOC_HEAP_POOL 

RWS_$ALLOC_HEAP_POOL 

Allocates heap (releasable read/write) storage from a specified pool. 

FORMAT 

storage_ptr = RWS_$ALLOC_HEAP_POOL(alloc_pool, storage_sz ) 

RETURN VALUE 

storage _ptr 

The address of the new storage space, in UNIV_PTR format. This is a 4-byte integer. A 
returned address of zero (NIL) means that RWS_$ALLOC_HEAP_POOL could not 
allocate the desired storage. 

INPUT PARAMETERS 

alloc _ pool 

Pool from which the storage will be allocated, in RWS_$POOL_T format. This is a 
2-byte integer. Specify one of the following predefined values: 

RWS_$GLOBAL_POOL 

Global pool makes storage accessible to all processes. Note that pointers 
are valid in all processes because they reserve the identical portion of 
address space. 

RWS_$STD_POOL 

Standard pool makes storage accessible to the calling program only. Most 
programs use this type. 

RWS_$STREAM_TM_POOL 

Stream pool makes storage accessible to the calling program and to a 
program invoked with a UNIX EXEC system call. Use this type when 
your program needs to pass information across a UNIX EXEC system 
call. 

storage _sz 

Number of bytes of storage needed. This is a 4-byte integer. 

USAGE 

RWS_$ALLOC_HEAP_POOL allocates a specified number of bytes of heap storage to 
the calling process and returns the address of the storage area. 

When you no longer need the storage, call RWS_$RELEASE_ HEAP _ POOL to return 
the storage to the pool from which it was allocated. 

Whether you allocate heap (releaseable read/write) storage with this call or read/write 
storage with RWS_$ALLOC_RW_POOL depends on how long you want to keep the 
storage. Once you allocate read/write storage, the storage exists until the program 
terminates. However, you can explicitly release heap storage once you have finished using 
it. The heap requires more system overhead initially to keep track of allocated storage. . 
Read/write storage does not require any system overhead. 



RWS RWS-6 



RWS $ALLOC HEAP POOL 



O 



(Currently, the overhead for RWS _$ALLOC_ HEAP _POOL is between 4 to 16 bytes - 
The exact amount of call overhead is subject to change.) 

Typically, you allocate heap storage if your program requires a substantial amount of 
storage for a limited time, or if you want to keep your working set as small as possible. 
You allocate read/write storage if you do not need to release storage before terminating a 
program, or if the amount of overhead for a heap is unacceptable. 

When allocating heap or read/write storage, you control how your program accesses storage 
by specifying the type of storage pool to use: 

o The standard pool (RWS_$STD_POOL) permits access to the calling process 
only. 

o The global pool (RWS _$GLOBAL_ POOL) permits access to all processes. 

• The stream pool (RWS_$STREAM_TM_POOL) permits access to the calling 
program and a program invoked with a UNIX EXEC system call. 

The global pool allows you to share information among processes. For example, you might 
want to create a global queue to pass messages between processes. Note that pointers are 
valid in all processes because all processes reserve an identical portion of address space. 

The stream pool allows you to make storage accessible between a calling process and an 
overlay process. For example, the IOS manager uses a stream pool to pass an open stream 
to a program invoked with an EXEC call. It stores information about that stream in a 
stream pool. 

The following table summarizes the aspects of each type of storage allocation. 
Summary of Types of Storage Allocation 



Read/Write Storage 

Standard Storage kept until program 

Pool exits or until it invokes 

a program with a UNIX 
EXEC system calj.. 



Heap Storage 

Storage kept until you 

release it with 
RWS_$RELEASE_HEAP. the 
program exits, or the 
program invokes a program 
with a UNIX EXEC call. 



No system overhead. 



About 16 bytes of 
system overhead. 



Storage available to local process only. 



Global 
Pool 



Storage kept until reboot 



Storage kept until 

you release it with 
RWS $RELEASE HEAP or reboot 



About 4 bytes of system 
overhead. 



About 4 bytes of system 
overhead . 



Storage available to all processes. 
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RWS $ALLOC HEAP POOL 



Summary of Types of Storage Allocation, Cont. 
Read/Write Storage Heap Storage 



Stream 
Pool 



NOTE: 



Storage kept until 
program exits . 

No system overhead. 



Storage kept until 

you release it with 
RWS $RELEASE HEAP. 



About 16 bytes of 
system overhead. 



Storage available to the local process or to a 
program invoked with a UNIX EXEC system call. 

Do not depend on the exact amount of system overhead 
used in RWS system calls . The amount of overhead is 
subject to change. 



Note that this call replaces the obsolete RWS _$ALLOC_ HEAP call, which we include for 
maintenance purposes only. For current and future development, use 
RWS_$ALLOC_HEAP_POOL. 

FORTRAN programmers: due to FORTRAN calling conventions, RWS_$ALLOC is 
currently the only RWS call you can use to allocate read /write storage. C programmers 
might want to use the C library routine MALLOC to allocate storage. 
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RWS $ ALLOC RW 



O 



o 



o 



RWS_$ALLOC_RW 

Allocates read/write storage for Pascal and C programs. This call is obsolete and is 
documented here for maintenance purposes only. You should replace it with 
RWS SALLOC RW POOL. 



FORMAT 

storage_ptr = RWS_$ALLOC_RW (storage_sz) 

RETURN VALUE 

storage _ptr 

The address of the new storage space, in UNIV_PTR format This is a 4-byte integer. A 
returned address of zero (NIL) means that RWS_$ALLOC_RW could not allocate the 
desired storage. 

INPUT PARAMETERS 

storage _sz 

The number of bytes of storage needed. This is a 4-byte integer. 

USAGE 

Note that RWS_$ALLOC_RW_POOL replaces this obsolete call, which we include for 
maintenance purposes only. For current and future development, use 
RWS_$ALLOC_RW_POOL. 

RWS_$ALLOC_RW allocates the specified number of bytes of read/write storage to the 
calling process and returns the address of the storage area. It allocates storage from the 
standard RWS pool, which makes the storage accessible to the calling program only. This 
call does not require any system overhead. 

FORTRAN programmers: due to FORTRAN calling conventions, RWS_$ALLOC is 
currently the only RWS call you can use to allocate read/write storage. 

C programmers might want to use the C library routine MALLOC to allocate storage. 
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RWS_$ALLOC_RW_POOL 

RWS_$ALLOC_RW_POOL 

Allocates read/write storage from a specified pool. 

FORMAT 

storage_ptr = RWS_$ALLOC_RW_POOL(alloc_pool, storage_sz ) 

RETURN VALUE 

storage _ptr 

The address of the new storage space, in UNIV_PTR format. This is a 4-byte integer. A 
returned address of zero (NIL) means that RWS_$ALLOC_RW_POOL could not 
allocate the desired storage. 

INPUT PARAMETERS 

alloc _ pool 

Pool from which storage will be allocated, in RWS_$POOL_T format. This is a 2-byte 
integer. Specify one of the following following predefined values: 

RWS_$GLOBAL_POOL 

Global pool makes storage accessible to all processes. Note that pointers 
are valid in all processes because they reserve the identical portion of 
address space. 

RWS_$STD_POOL 

Standard pool makes storage accessible to the calling program only. Most 
programs use this type. 

RWS _ $STREAM _ TM _ POOL 

Stream pool makes storage accessible to the calling program and to a 
program invoked with a UNIX EXEC system call. Use this type when 
your program needs to pass information across a UNIX EXEC system 
call. 

storage _sz 



.ge _ sz 

Number of bytes of storage needed. This is a 4-byte integer. 



USAGE 



RWS _$ALLOC_RW_ POOL allocates a specified number of bytes of read/write storage 
to the calling process and returns the address of the storage area. 

Whether you allocate read/write storage with this call or heap (releaseable read/write) 
storage with RWS _$ALLOC_ HEAP _ POOL depends on how long you want to keep the 
storage. Once you allocate read/write storage, the storage exists until the program 
terminates. However, you can explicitly release heap storage once you have finished using 
it. The heap requires more system overhead initially, to keep track of allocated storage. 
Read/ write storage does not require any system overhead. 
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RWS $ALLOC RW POOL 



O 



o 



o 



Typically, you allocate read/write storage if you do not need to release storage before 
terminating a program, or if the amount of overhead for a heap is unacceptable. You 
allocate heap storage if your program requires a substantial amount of storage for a limited 
time, or if you want to keep your working set as small as possible. 

When allocating read/write or heap storage, you control how your program accesses storage 
by specifying the type of storage pool to use: 

• The standard pool (RWS _$STD_ POOL) permits access to the calling process 
only. 

• The global pool (RWS_$GLOBAL_POOL) permits access to all processes. 

• The stream pool (RWS _$STREAM_TM_ POOL) permits access to the calling 
program and a program invoked with a UNIX EXEC system call. 

The global pool allows you to share information among processes. For example, you might 
want to create a global queue to pass messages between processes. Note that pointers are 
valid in all processes because all processes reserve an identical portion of address space. 

The stream pool allows you to make storage accessible between a calling process and an 
overlay process. For example, the IOS manager uses a stream pool to pass an open stream 
to a program invoked with an EXEC call. It stores information about that stream in a 
stream pool. 

The following table summarizes the aspects of each type of storage allocation. 
Summary of Types of Storage Allocation 



Read/Write Storage 

Standard Storage kept until program 

Pool exits or until it invokes 

a program with a UNIX 
EXEC system call . 



Heap Storage 

Storage kept until you 

release it with 
RWS_$RELEASE_HEAP . the 
program exits, or the 
program invokes a program 
with a UNIX EXEC call. 



About 16 bytes of 
system overhead. 



No system overhead. 

Storage available to local process only. 



Global 
Pool 



Storage kept until reboot 



Storage kept until 

you release it with 
RWS $RELEASE HEAP or reboot 



About 4 bytes of system 
overhead. 



About 4 bytes of system 
overhead. 



Storage available to all processes 
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RWS $ALLOC RW POOL 



Summary of Types of Storage Allocation, Cont. 
Read/Write Storage Heap Storage 



Stream 
Pool 



Storage kept until 
program exits . 

No system overhead. 



Storage kept until 

you release it with 
RWS $RELEASE HEAP. 



About 16 bytes of 
system overhead. 



Storage available to the local process or to a 
program invoked with a UNIX EXEC system call. 



NOTE: Do not depend on the exact amount of system overhead 
used in RWS system calls. The amount of overhead is 
subject to change. 



Note that this call replaces the obsolete RWS _$ ALLOC _RW call, which we include for 
maintenance purposes only. For current and future development, use 
RWS_$ALLOC_RW_POOL. 

FORTRAN programmers: due to FORTRAN calling conventions, RWS_$ALLOC is 
currently the only RWS call you can use to allocate read/write storage. C programmers 
might want to use the C library routine MALLOC to allocate storage. 
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RWS- 12 



) 



RWS _ $RELEASE_HEAP 

RWS _ $RELEASE_HEAP 

Releases storage allocated by the RWS _$ALLOC_ HEAP call. This call is obsolete and is 
documented here for maintenance purposes only. You should replace it with 
RWS_$ALLOC_HEAP_POOL. 

FORMAT 

RWS_$RELEASE_HEAP (storage_ptr , status) 

INPUT PARAMETERS 

storage ptr 

The address heap storage space, in UNIV_PTR format. This is a 4-byte integer. This 
must be the pointer returned by a call to RWS _$ALLOC_ HEAP. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the RWS 
Data Types section for more information. 

USAGE 

Note that RWS _$RELEASE_ HEAP _ POOL replaces this less efficient call, which we 
> include for maintenance purposes only. For current and future development, use 

RWS _ $RELEASE_HEAP _POOL. 

Use this call to release the storage that you previously allocated with 
RWS $ALLOC HEAP. 



o 



o 
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RWS _ $RELEASE_HEAP _POOL 

RWS_$RELEASE_HEAP_POOL . /— x 

Releases storage to the pool from which it was allocated. "" — 

FORMAT 

RWS_$RELEASE_HEAP_POOL (storage_ptr . alloc_pool, status) 

INPUT PARAMETERS 

storage _ptr 

Pointer to the address heap storage space, in UNIV_PTR format. This is a 4-byte integer. 
This must be the pointer returned by a call to RWS _$ALLOC_ HEAP _ POOL. 

alloc _ pool 

Pool where storage will be returned to, in RWS_$POOL_T format. This is a 2-byte 

integer. Specify the same value you specified in the RWS_$ALLOC_HEAP_POOL call, ^-^ 

which is one of the following predefined values: ( 

RWS_$GLOBAL_POOL 

Global pool makes storage accessible to all processes. Note that pointers 
are valid in all processes because they reserve the identical portion of 
address space. 

RWS_$STD_POOL 

Standard pool makes storage accessible to the calling program only. Most 

programs use this type. f 

v_ ■ 

RWS _ $STREAM_ TM_POOL 

Stream pool makes storage accessible to the calling program and to a 
program invoked with a UNIX EXEC system call. Use this type when 
your program needs to pass information invoked with a UNIX EXEC 
system call. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the RWS 
Data Types section for more information. 

USAGE 

Use RWS_$RELEASE_HEAP_POOL to release storage to the pool from which it was 
allocated. You allocate storage to a specific pool with the RWS _$ALLOC_ HEAP _ POOL 
call. 

RWS _ $ALLOC __ HEAP _ POOL dynamically allocates storage from one of the three types 
of storage pools, and returns a pointer to the new storage. When you no longer need the 
storage, you release it by passing the " storage _ptr" and " alloc _ pool" to 
RWS_$RELEASE_HEAP_POOL. RWS _$RELEASE_ HEAP _ POOL return the 
storage to the pool from which it was allocated. 



RWS RWS- 14 



RWS $RELEASE HEAP POOL 



Note that this call replaces the less efficient RWS _$RELEASE_ HEAP call, which we 
include for maintenance purposes only. For current and future development, use 
RWS $RELEASE HEAP POOL. 



o 



o 



o 



RWS- 15 RWS 



RWS ERRORS 



ERRORS 

RWS _ $LEVEL _FAILURE 

User program wrote over the storage where the system stored the program level 
information. 

RWS_$NOT_HEAP_ENTRY 

Argument to RWS _$RELEASE_ HEAP did not refer to storage allocated with 
RWS_$ALLOC_HEAP. 

RWS _ $SCRIBBLED _ OVER 

User program wrote over the storage where the system stored the heap's process 
information. 

RWS _ $ WRONG _LEVEL 

Attempted to release storage that was allocated by a program at a superior (lower) 
program level. This error can occur when using RWS_$STD_POOL or 
RWS $STREAM TM POOL. 



( 



v. 
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SIO 



The SIO (Serial I/O) programming calls handle communications to devices across serial I/O lines. 
This section describes their data types, call syntax, and error codes. Refer to the Introduction at 
the beginning of this manual for a description of data-type diagrams and call syntax format. 



O 



o 



o 



SIO-1 SIO 



SIO DATA TYPES 



CONSTANTS 



SIO_$50 

SIO _ $75 

SIO_$110 

SIO_$134 

SIO_$150 

SIO _ $300 

SIO _ $600 

SIO_$1200 

SIO_$2000 

SIO _ $2400 

SIO _ $3600 

SIO _ $4800 

SIO _ $7200 

SIO_$9600 

SIO _$ 19200 

SIO _ $EVEN _ PARITY 

SIO_$MAX_LINE 

SIO_$NO_PARITY 

SIO _ $ ODD _ PARITY 

SIO_$STOP_l 

SIO_$STOP_l_POINT_5 

SIO_$STOP_2 

SIO_$5BPC 

SIO_$6BPC 

SIO_$7BPC 

SIO $8BPC 



Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Baud rate. 

Possible parity value. 

Maximum number of SIO lines. 

Possible parity value. 

Possible parity value. 

Possible stop bit value. 

Possible stop bit value. 

Possible stop bit value. 

Bits per character value. 

Bits per character value. 

Bits per character value. 

Bits per character value. 
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SIO DATA TYPES 



DATA TYPES 



SIO $ERR ENABLES T 



A 2-byte integer. Determines which errors are 
enabled. Any combination of the following 
predefined values: 



SIO _ $CHECK_PARITY 

Check for received parity errors. 

SIO_$CHECK_FRAMING 

Check for received framing errors. 

SIO _ $CHECK_DCD _ CHANGE 

Check for error when DCD line changes state. 



SIO $LINE T 



SIO $OPT T 



SIO _ $ CHECK _ CTS _ CHANGE 

Check for error when CTS line changes state. 

A 2-byte integer. SIO line number. Possible values 
are integers from through SIO _$MAX_ LINE 
(3). 

A 2-byte integer. An SIO option. One of the 
following predefined values: 



O 



SIO_$ERASE 

Set erase character. 

SIO _ SKILL 

Set kill character. 



SIO_$EOFCHR 

Set EOF character. 



O 



SIO_$RAW 

Transparent input and output. 

SIO_$NO_ECHO 
Do not echo input. 



SIO_$NO_NL 

Do not special case newlines. 

SIO _$ SPEED 
Set bit rate. 

SIO_$HOST_SYNC 

Use xoff/xon to synchronize with host. 

SIO_$NLC_DELAY 
Constant delay for newlines. 



O 



SIO_$QUIT_ENABLE 

Enable quits from this line to calling process. 
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SIO DATA TYPES 



SIO_$INPUT_SYNC 

Respond xoff/xon on receive side. 

SIO_$LINE 

Return line number (inquire only). 

SIO_$RTS 
Set/clear RTS bit. 

SIO_$DTR 
Set/clear DTR bit. 

SIO_$DCD 

Read DTR bit (inquire only). 

SIO_$DCD_ENABLE 
Enable fault on DCD loss. 

SIO_$CTS 

Read CTS bit (inquire only). 

SIO_$CTS_ENABLE 

Enable CTS gating of output. 

SIO_$PARITY 

Control parity setting/processing. 

SIO_$BITS_PER_CHAR 
Number of bits per character. 

SIO_$STOP_BITS 
Number of stop bits. 

SIO _ $ERR_ENABLE 
Enable error reporting. 

SIO _ $SEND _BREAK 

Establish break condition on line. 

SIO_$QUITCHR 
Set quit character. 

SIO_$BP_ENABLE 

Enable bit pad processing on line. 

SIO_$INT_ENABLE 

Enable interrupts in this process. 

SIO_$INTCHR 

Set interrupt character. 

SIO_$SUSP_ENABLE 

Enable process suspension character. 

SIO_$SUSPCHR 

Set process suspension character. 
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SIO DATA TYPES 



SIO_$RAW_NL 

Display NL/CR on NL output in raw mode. 

SIO_$UNUSED 
Unused. 

SIO _$HUP_ CLOSE 
Set hangup-on-close. 

SIO _$RTS_ ENABLE 
Enable RTS flow control. 

SIO_$SPEED_FORCE 

Set bit rate, even if disturbs partner channel. 



SIO_$FLUSH_IN 
Flush input buffer. 

SIO_$FLUSH_OUT 
Flush output buffer. 



SIO $VALUE T 



O 



predefined 
type 



sio $err enables t 



SIO_$DRAIN_OUT 

Wait for output buffer to drain. 

Value corresponding to SIO options. The diagram 
below illustrates the SIO_$VALUE_T data type: 



byte: 
offset 


7 C 


) 


field name 


0: 


char 




c 




or 






0: 


integer 


i 




or 






0: 


boolean 




b 




or 






0: 


integer 


es 



Field Description: 



A character value. 



A 2-byte integer value. 



o 



A Boolean value. 
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SIO DATA TYPES 



STATUS $T 



A set of enabled errors. This is a 2-byte field. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 


31 






field name 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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SIO_$CONTROL 

SIO_$CONTROL 

Changes current settings of serial line options and values. 

FORMAT 

SIO_$CONTROL (stream-id, option, value, status) 

INPUT PARAMETERS 

stream- id 

Stream ID of a stream attached to a serial line. This is a 2-byte integer. 

The stream specified by stream-id must be attached to a serial line. Any other attachment 
results in an error. 

option 

The attribute that is to be set, in SIO_$OPT_T format. This is a 2-byte integer. Specify 
only one of the following predefined values: 

SIO _ $BITS _ PER _ CHAR 

Sets the number of bits per character. This option takes a predefined 
2-byte integer value. The default is SIO_$8BPC, which is 8 bits per 
character. Possible choices are: SIO_$xBPC, where x may be 5, 6, 7, or 



SIO_$BP_ENABLE 

Enables/disables processing of bit pad input from a graphics tablet. This 
option takes a Boolean value. The default is FALSE (disabled). 

When enabled, data received on the SIO line is not delivered through 
IOS_$GET. Instead, the SIO driver interrupt routine accumulates data 
and passes it. a point at a time to the display driver. During this 
processing, subsequent points within plus or minus two in both x and y 
dimensions are ignored. 

SIO_$CTS No meaning for this call. 

SIO_$CTS_ENABLE 

Sets whether the CTS_ENABLE mode is on or off. This option takes a 
Boolean value. The default is FALSE (off). 

Some devices use one of the RS-232 control lines for flow control instead 
of XON/XOFF. If such a line is wired to the CTS line on the connector 
and if SIO _$CTS_ ENABLE is TRUE, then transmission will be 
inhibited whenever CTS is FALSE. 

SIO_$DCD No meaning for this call. 

SIO_$DCD_ENABLE 

Sets whether' the DCD_ENABLE mode is on or off. This option takes a 
Boolean value. The default is FALSE (off). 
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If the connection is broken (i.e., the remote modem hangs up) the DCD 
line becomes FALSE. If SIO _$D CD _ ENABLE is TRUE then a fault 
with status FAULT _$STOP will occur at the time of the transition of 
DCD from TRUE to FALSE. 

SIO_$DRAIN_OUT 

Causes the process to wait until all the characters in the output buffer 
have been transmitted before returning. This option takes a Boolean 
value. The default is FALSE (off). 

SIO_$DTR Sets the state of the outgoing DTR (Data Terminal Ready) line. This 

option takes a Boolean value. The default is TRUE (on). 

On most modems the DTR line controls whether the modem will answer 
incoming calls (i.e., when DTR is TRUE.) When it is reset it causes the 
modem to hang up the phone line. 

SIO_$EOFCHR Sets the end-of-file character. This option takes a character value. The 
default is CTRL/Z. 

SIO_$ERASE Sets the erase character, which erases the character immediately before 
the current cursor position. This option takes a character value. The 
default is < BACKSPACE >. 

SIO _ $ERR _ ENABLE 

Sets which kinds of errors can be reported in calls to IOS_$GET on this 
stream. This option takes a set of values, in 

SIO _$ERR_ ENABLES _T format. Specify any combination of the 
following predefined 2-byte integer values: 

SIO _ $CHECK _ PARITY 

Report received parity errors. 

SIO _ $CHECK _ FRAMING 

Report received framing errors. This value is set by 
default. 

SIO _ $CHECK_DCD _ CHANGE 

Report an "error" when DCD line changes state. 

SIO _$CHECK_CTS_ CHANGE 

Report an "error" when CTS line changes state. 

SIO_$FLUSH_IN 

Causes the input buffer of an SIO line to be flushed. This option takes a 
Boolean value. The default is FALSE (off). 

SIO_$FLUSH_OUT 

Causes the output buffer of an SIO line to be flushed. This option takes 
a Boolean value. The default is FALSE (off). 

SIO _$HOST_ SYNC 

Sets whether HOST _ SYNC mode is on or off. This option takes a 
Boolean value. The default is TRUE (on). 
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SIO_$CONTROL 

In HOST _ SYNC mode, the node sends XOFF (CTRL/S) when its input 
buffer begins to fill, and XON (CTRL/Q) when its input buffer begins to 
empty again. This allows for synchronization of high-speed data transfer 
from computer to computer. 

SIO_$HUP_ CLOSE 

Causes the modem to be hung up on the last close (IOS_$CLOSE) of the 
SIO line. The hangup is performed by dropping 'DTR for 3/4 second. 

SIO_$INPUT_SYNC 

Sets whether the incoming sync mode is on or off. This option takes a 
Boolean value. The default is FALSE (off). 

It is like HOST _ SYNC except it controls processing of incoming XON 
(CTRL/Q) or XOFF (CTRL/S). It works in raw or cooked mode. 

SIO _ $INT _ ENABLE 

Enables/disables interrupts for the current process. This option takes a 
Boolean value. The default is FALSE (disabled). 

SIO_$INTCHR Sets the process interrupt character. (This option is used primarily by 
DOMAIN/LX.) This option takes a character value. The default is 
FALSE (CRTL/C). 

SIO_$KILL Sets the kill character, which deletes characters from the cursor position 

to the end of the line. This option takes a character value. The default 
is CTRL/X. 

SIO_$LINE No meaning for this call. 

SIO_$NLC_DELAY 

Sets the value of a time delay to be used following transmission of a line 
feed character, to allow for carriage motion, scrolling time, and so on. 
This option takes a 2-byte integer value, specifying the number of 
milliseconds of delay. The default is zero. 

SIO _$NO_ ECHO 

Sets whether NO_ECHO mode is on or off. In NO_ECHO mode, input 
characters are not automatically echoed as output. This mode may be 
used to support a half-duplex connection. NO_ECHO mode is off by 
default. 

SIO_$NO_NL Sets whether NO_NL mode is on or off. This option takes a Boolean 
value. The default is FALSE (off). . 

Normally, newline characters (decimal 10) are transmitted as a 
carriage-return, line-feed. In NO_NL mode, the newline character is 
transmitted as is. This mode makes output transparent without going to 
raw input. 

SIO_$PARITY Sets the state of parity detection or parity generation. This option takes 
a predefined 2-byte integer value. The default is SIO _$NO_ PARITY. 
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Possible choices are: SIO _$ ODD _ PARITY, SIO _$EYEN_ PARITY, 
and SIO_$NO_PARITY. 

If parity is enabled (whether odd or even) then one bit is added to each 
character. The parity bit is checked by the hardware on received 
characters and errors are reported, subject to the SIO _$ERR_ ENABLE 
option. If the number of bits per character is fewer than 8, then the 
parity bit is delivered with the data in raw mode and is stripped in 
cooked mode. 

SIO_$QUITCHR 

Sets the quit character This option takes a character value. The default 
is CTRL/]. 

SIO _ $QUIT _ ENABLE 

Sets whether THE quit _ enable mode is on or off. This option takes a 
Boolean value. The default is FALSE (off). 

In quit _ enable mode, the node responds to CTRL/] and to the 
<BREAK> key, if any. The response is a quit fault in the process using 
SIO_$QUIT_ENABLE. If SIO _$ QUIT _ ENABLE is FALSE, then 
neither the <BREAK> key nor the CTLR/] sequence has any effect. In 
raw input mode, only the <BREAK> and CTRL/] sequence causes a 
quit fault. 

SIO_$RAW Sets whether raw mode is on or off. This option takes a Boolean value. 

The default is FALSE (off). In raw mode, full 8-bit bytes are transmitted 
in both directions, without any interpretation. Each call (e.g., 
IOS_$GET and STREAM_$GET_REC) that reads from the stream 
returns as many bytes as have been received since the last call. 

When raw mode is turned on or off, any input that your program has 
received, but has not yet read, is flushed from the input buffer. 

SIO_$RAW_NL 

Sets whether NO_NL mode is on or off in raw mode. (i.e., when 
SIO_$RAW is TRUE). This option takes a Boolean value. The default 
is FALSE (off). 

Normally, newline characters (decimal 10) are transmitted as a 
carriage-return, line- feed. In NO_NL mode, the newline character is 
transmitted as is. This mode makes output transparent without going to 
raw input. 

SIO_$RTS Sets the state of the RTS (Request to Send) line. This option takes a 

Boolean value. The default is TRUE (on). 

The RTS line is an outgoing line. 

v 

SIO_$RTS_ENABLE 

Enables/disables the RTS (Return to Send) Line. This is a Boolean 
value. The default is FALSE (off). 
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If TRUE, the operating system handles flow control. For this to work 
properly the CTS line must also be enabled. 

SIO _ $SEND _ BREAK 

Causes a break condition on the line. This option takes a 2-byte integer 
value, specifying the duration of the break, in milliseconds. A reasonable 
value is 200. 

SIO_$SPEED Sets the baud rate of the line. This option takes a predefined 2-byte 
integer value. The default is SIO _ $9600. 

Possible values are: 

SI0_$50, SI0_$75, SI0_$110, SI0_$134. SI0_$150, 
SI0_$300. SI0_$600. SI0_$1200, SI0_$2000. SIO_$2400, 
SI0_$3600, SI0_$4800. SI0_$7200, SI0_$9600. SI0_$19200. 

Some machine types are configured so that certain SIO lines are 
"partnered" with each other. If you use the SIO_$SPEED option to set 
a line's baud rate to a rate that is incompatible with the partner's rate, 
you receive the error status, SIO _$INCOMPATIBLE_ SPEED. 
However, you can override this error using the SIO _$SPEED_ FORCE 
option. If you use SIO_$SPEED FORCE to set the speed of a line and 
the new speed is incompatible with the partner, the speed of the partner 
is changed to 9600 baud. See the Usage section for details about 
partnered lines and incompatible speeds. 

SIO _ $SPEED _FORCE 

Sets the baud rate of the line even if the partner line's speed is 
incompatible. This option takes a predefined 2-byte integer value. 

Possible values are the same as for SIO_$SPEED: 

SI0_$50, SI0_$75, SI0_$110. SI0_$134. SI0_$150, 

SI0_$300, SI0_$600, SI0_$1200, SI0_$2000, SI0_$2400. 
SI0_$3600, SI0_$4800, SI0_$7200. SI0_$9600. SI0_$19200. 

Some machine types are configured so that certain SIO lines are 
"partnered" with each other. If you use the SIO_$SPEED option to set 
a line's baud rate to a rate that is incompatible with the partner line's 
rate, you receive the error status, SIO _$ INCOMPATIBLE _ SPEED. 
However, you can override this error using the SIO _$SPEED_ FORCE 
option. If you use SIO_$SPEED FORCE to set the speed of a line and 
the new speed is incompatible with the partner, the speed of the partner 
is changed to 9600 baud. See the Usage section for details about 
partnered lines and incompatible speeds. 



SIO _$STOP_ BITS 



.TS 

Sets the number of stop bits. This option takes a predefined 2-byt 
integer value. The default is SIO _$STOP_l. Possible values art 
SIO_$STOP_x where x may be 1, l_POINT_5, or 2. 



e 
are: 
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SIO _ $SUSP _ENABLE 

Enables/disables suspend faults for the current process. This option 
takes a Boolean value. The default is FALSE (disabled). 

SIO_$SUSPCHR 

Sets the process suspend character. (This option is used primarily by 
DOMAIN/DC.) This option takes a character value. The default is 
CRTL/P. 

value 

Each of the SIO_$CONTROL options accepts a corresponding value. For the character 
options, the value is simply the character. For the mode-setting options, the value is a 
Boolean (LOGICAL) data item. For most of the remaining options, the value is a 2-byte 
integer. In one case, you may specify a set of values. The type of value required for each 
option is described along with the option, above. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the SIO 
Data Types section for more information. 

Possible values are: 

STATUS _$OK The operation completed successfully. 

IOS_$NOT_OPEN 

No stream is open on the specified stream ID. 

SIO_$STREAM_NOT_SIO 

The specified stream ID is not connected to a serial line. 

SIO _$BAD_ OPTION 

The call specified an invalid option name. 

SIO _ $INCOMPATIBLE _ SPEED 

The specified speed is incompatible with the speed of the line's partner. 

USAGE 

To poll the serial line for unread input, use IOS_$GET with the IOS_$COND_OPT 
option. 

The hardware configuration for some machine types is such that certain SIO lines are 
"partnered" with each other. 
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Below is a list of machine types and the SIO lines that are partnered on them. 



Machine Type 


Partnered Lines 


DN400 


No 


DN420 


Partners 


DN600 




DN300 


1,2 


DSP80 


1.2 


DN460 


0.1 


DN660 


2.3 


DN550 


1.2 


DN3000 


No Partners 



A characteristic of partnered lines is that some baud rates are incompatible. The following 
lists show the baud rates that are incompatible for partnered lines. 
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Incompatible Rates A 


Incompatible Rates B 


SI0_$50 
SI0_$7200 


SI0_$75 
SI0_$150 
SIO_$2000 
SI0_$19200 



If one partner is set to a baud rate in the A list, attempting to set the other partner to a 
baud rate in the B list (using the SIO_$SPEED option) will result in the error 
SIO _$INCOMPATIBLE_ SPEED. The same is true for the reverse (having a partnered 
line set to a rate in the B list and attempting to set its partner to a rate in the A list). 
Speeds other than those in the two lists are compatible. 

You may force a line's baud rate to a rate that is incompatible to its partner, by using the 
SIO _$SPEED_ FORCE option. This will change the specified line's speed; however, it 
will also change the speed of the partnered line to SIO _ $9600 (which is always a 
compatible speed). 



O 
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SIO_$INQUIRE 

SIO_$INQUIRE 

Obtains current settings of serial line options and values. 

FORMAT 

SIO_$INQUIRE (stream-id. option, value, status) 

INPUT PARAMETERS 

stream- id 

Stream-id of a stream attached to a serial line. This is a 2-byte integer. 

option 

The attribute that is to be reported, in SIO_$OPT_T format. This is a 2-byte integer. 
One of the following predefined values: 

SIO _ $BITS _PER _ CHAR 

Returns the number of bits per character. This option takes a predefined 
2-byte integer value. The default is SIO_$8BPC, which is 8 bits per 
character. Possible choices are: SIO_$xBPC, where x may be 5, 6, 7, or 



SIO_$BP_ENABLE 

Enables/disables processing of bit pad input from a graphics tablet. This 
option takes a Boolean value. The default is FALSE (disabled). 

When enabled, data received on the SIO line is not delivered through 
IOS_$GET. Instead, the SIO driver interrupt routine accumulates data 
and passes it a point at a time to the display driver. During this 
processing, subsequent points within plus or minus two in both x and y 
dimensions are ignored. 

SIO_$CTS Returns the state of the CTS (Clear to Send) line. This is an incoming 

line. 

r 

SIO_$CTS_ENABLE ^ 

Returns whether CTS _ ENABLE mode is on or off. This option takes a 
Boolean value. The default is FALSE (off). 

Some devices use one of the RS-232 control lines for flow control instead 
of XON/XOFF. If such a line is wired to the CTS line on the connector 
and if SIO _$CTS_ ENABLE is TRUE, then transmission will be 
inhibited whenever CTS is FALSE. 

SIO_$DCD Reports the state of the DCD (Data Carrier Detect) line. It is an 

incoming line, which usually means there is an active modem at the other 
end of the phone line. 

SIO_$DCD_ENABLE 

Returns whether DCD_ENABLE mode is on or off. This option takes a 
Boolean value. The default is FALSE (off). 
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If the connection is broken (i.e., the remote modem hangs up) the DCD 
line becomes FALSE. If SIO _$D CD _ ENABLE is TRUE then a fault 
with status FAULT _$STOP occurs at the time of the transition of DCD 
from TRUE to FALSE. 

SIO_$DRAIN_OUT 

No meaning for this call. 

SIO_$DTR Returns the state of the outgoing DTR (Data Terminal Ready) line. This 

option takes a Boolean value. The default is TRUE (on). 

On most modems the DTR line controls whether the modem answers 
incoming calls (i.e., when DTR is TRUE.) When it is reset it causes the 
modem to hang up the phone line. 

SIO_$EOFCHR Returns the end-of-file character. This option takes a character value. 
The default is CTRL/Z. 

SIO_$ERASE Returns the erase character, which erases the character immediately 

before the current cursor position. This option takes a character value. 
The default is < BACKSPACE >. 

SIO _ $ERR _ ENABLE 

Returns which kinds of errors can be reported in calls to IOS_$GET on 
this stream. This option takes a set of values, in 
SIO _$ERR_ ENABLES _T format. Specify any combination of the 
following predefined 2-byte integer values: 

SIO _ $CHECK _PARITY 

Report received parity errors. 

SIO _ $CHECK_FRAMING 

Report received framing errors. This value is set by 
default. 

SIO_$CHECK_DCD_CHANGE 

Report an "error" when DCD line changes state. 

SIO _ $CHECK _ CTS _ CHANGE 

Report an "error" when CTS line changes state. 

SIO_$FLUSH_IN 

No meaning for this call. 

SIO_$FLUSH_OUT 

No meaning for this call. 

SIO _$HOST_ SYNC 

Returns whether the HOST _ SYNC mode is on or off. This option takes 
a Boolean value. The default is TRUE (on). 

OIn HOST _ SYNC mode, the node sends XOFF (CTRL/S) when its input 
buffer begins to fill, and XON (CTRL/Q) when its input buffer begins to 
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empty again. This allows for synchronization of high-speed data transfer 
from computer to computer. 

SIO_$HUP_ CLOSE 

Causes the modem to be hung up on the last close (IOS_$CLOSE) of the 
SIO line. The hangup is performed by dropping DTR for 3/4 second. 
This option takes a Boolean value. The default is FALSE (off). 

SIO _ $INPUT _ SYNC 

Returns whether incoming sync mode is on or off. This option takes a 
Boolean value. The default is FALSE (off). 

It is like HOST _ SYNC except it controls processing of {_ incoming _} 
XON (CTRL/Q) or XOFF (CTRL/S).. It works in raw or cooked mode. 

SIO_$INT_ENABLE 

Enables/disables interrupts for the current process. This option takes a 
Boolean value. The default is FALSE (disabled). 

SIO_$INTCHR Returns the process interrupt character. (This option is used primarily 
by DOMAIN/DC.) This option takes a character value. The default is 
FALSE (CRTL/C). 

SIO_$KILL Returns the kill character, which deletes characters from the cursor 

position to the end of the line. This option takes a character value. The 
default is CTRL/X. 

SIO_$LINE Returns the serial line number corresponding to the stream ID. This 

option returns an integer value from to 3. 

SIO _$NLC_ DELAY 

Returns the value of a time delay to be used following transmission of a 
line feed character, to allow for carriage motion, scrolling time, and so 
on. This option takes a 2-byte integer value, specifying the number of 
milliseconds of delay. The default is zero. 

SIO_$NO_ECHO 

Returns whether the NO _ ECHO mode is on or off. In NO _ ECHO 
mode, input characters are not automatically echoed as output. This 
mode may be used to support a half-duplex connection. NO _ ECHO 
mode is off by default. 

SIO_$NO_NL Returns whether the NO_NL mode is on or off. This option takes a 
Boolean value. The default is FALSE (off). 

Normally, newline characters (decimal 10) are transmitted as a 
carriage-return, line-feed. In NO_NL mode, the newline character is 
transmitted as is. This mode makes output transparent without going to 
raw input. 

SIO_$PARITY Returns the state of parity detection or parity generation. This option 
takes a predefined 2-byte integer value. The default is 
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SIO_$NO_PARITY. Possible choices are: SIO _$ ODD _ PARITY, 
and SIO_$EVEN_PARITY, and SIO _$NO_ PARITY. 

If parity is enabled (whether odd or even) then one bit is added to each 
character. The parity bit is checked by the hardware on received 
characters and errors are reported, subject to the SIO _$ERR_ ENABLE 
option. If the number of bits per character is fewer than 8, then the 
parity bit is delivered with the data in raw mode and is stripped in 
cooked mode. 



SIO_$QUITCHR 



Returns the quit character, 
default is CTRL/]. 



This option takes a character value. The 
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SIO _ $QUIT _ENABLE 

Returns whether the QUIT _ ENABLE mode is on or off. This option 
takes a Boolean value. The default is FALSE (off). 

In QUIT _ ENABLE mode, the node responds to CTRL/] and to the 
<BREAK> key, if any. The response is a quit fault in the process using 
SIO _$QUIT_ ENABLE. If SIO _$ QUIT _ ENABLE is FALSE then 
neither the < BREAK > key nor the CTLR/] sequence has any effect. In 
raw input mode only the <BREAK>, and CTRL/] sequence causes a 
quit fault. 

SIO_$RAW Returns whether raw mode is on or off. This option takes a Boolean 

value. The default is FALSE (off). In raw mode, full 8-bit bytes are 
transmitted in both directions, without any interpretation. Each call 
(e.g., IOS_$GET and STREAM_$GET_REC) that reads from the 
stream returns as many bytes as have been received since the last call. 

When raw mode is turned on or off, any input that your program has 
received, but has not yet read, is flushed from the input buffer. 
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SIO $RAW NL 



Returns whether the NO_NL mode is on or off in raw mode. (i.e., when 
SIO_$RAW is TRUE). This option takes a Boolean value. The default 
is FALSE (off). 

Normally, newline characters (decimal 10) are transmitted as a 
carriage-return, line-feed. In NO_NL mode, the newline character is 
transmitted as is. This mode makes output transparent without going to 
raw input. 



SIO_$RTS Returns the state of the RTS (Request to Send) line. 

Boolean value. The default is TRUE (on). 

The RTS line is an outgoing line. 



This option takes a 



SIO_$RTS_ENABLE 

Enables/disables the RTS (Return to Send) Line, 
value. The default is FALSE (off). 



This is a Boolean 
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If TRUE, the operating system handles flow control. For this to work 
properly the CTS line must also be enabled. 

SIO _ $SEND _BREAK 

No meaning for this call. 

SIO_$SPEED Returns the baud rate of the line. This option takes a predefined 2-byte 
integer value. The default is SIO _ $9600. 

Possible values are: 

SI0_$50, SI0_$75, SI0_$110, SI0_$134. SI0_$150, 
SI0_$300, SI0_$600, SI0_$1200, SI0_$2000, SI0_$2400, 
SI0_$3600. SI0_$4800. SI0_$7200. SIO_$9600, SI0_$19200 . 

SIO _ $SPEED _FORCE 

No meaning for this call. 

SIO_$STOP_BITS (^ 

Returns the number of stop bits. This option takes a predefined 2-byte 
integer value. The default is SIO _$STOP_l. Possible values are: 
SIO_$STOP_x where x may be 1, l_POINT_5, or 2. 

SIO _ $SUSP _ENABLE 

Enables/disables suspend faults for the current process. This option 
takes a Boolean value. The default is FALSE (disabled). 

SIO_$SUSPCHR V, 

Returns the process suspend character. (This option is used primarily by 
DOMAIN/LX.) This option takes a character value. The default is 
CRTL/P. 

OUTPUT PARAMETERS 

value /- 

Each of the SIO_$INQUIRE options returns a corresponding value. For the character ( 

options, the value is simply the character. For the mode-setting options, the value is a 
Boolean (LOGICAL) data item. For most of the remaining options, the value is a 2-byte 
integer. In one case, a set of values may be returned. The type of value returned for each 
option is described along with the option, above. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the SIO 
Data Types section for more information. 

Possible values are: 

STATUS _$OK The operation completed successfully. 

IOS_$NOT_OPEN 

No stream is open on the specified stream ID. 

SIO _ $STREAM_ NOT _ SIO 

The specified stream ID is not connected to a serial line. 

SIO SIO- 18 



o 



SIO_$INQUIRE 



SIO_$BAD_ OPTION 

The call specified an invalid option name. 



USAGE 



The stream specified by stream ID must be attached to a serial line. Any other attachment 
results in an error. 

When raw mode is turned on or off, any input that your program has received, but has not 
yet read, is flushed from the input buffer. 

To poll the serial line for unread input, use IOS_$GET with the IOS_$COND_OPT 
option. 
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ERRORS 



STATUS _$OK 

Successful completion. 

SIO _$BAD_ OPTION 

Bad option parameter. 

SIO _ $ILLEGAL _ STRID 

Illegal stream ID. 

SIO _ $INCOMPATIBLE _ SPEED 

Speed incompatible with partner SIO line. 
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The SMD (Screen Manager) programming calls provide direct control over black-and-white 
displays. This section describes the call syntax and the error codes. Refer to the Introduction at 
the beginning of this manual for a description of call syntax format. Refer to the SMD insert 
files for data-type descriptions. 
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SMD_$BLT_U 

SMD_$BLT_U 

Starts a bit transfer from one area of display memory to another. 

FORMAT 

SMD_$BLT_U (registers, status) 

INPUT PARAMETERS 

registers 

Values for the BLT register, in SMD_$BLT_REGS_T format. This is a thirteen-element 
array of 2-byte integers. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$BLT_U starts the block transfer within display memory. 

The BLT register contains values for CS; CD; source and destination Xs, Xe, Ys, and Ye; 
and the display mode. 

In FORTRAN programs, specify the display mode as the sum of selected variables from 
Table SMD-1. 

By default, the display driver waits for the BLT to complete before returning to the calling 
program. (This is a "busy" wait, meaning the CPU is actiye while waiting.) If the display 
mode includes IDONE, however, control returns to the caller immediately, and generates 
the SMD event SMD_$EVENT_ SCROLL _ BLT _ COMPLETE (see 
SMD_$EVENT_WAIT_U) when it finishes. 

If the display mode includes IDONE, control returns to the calling program immediately, as 
noted above. However, if display memory is mapped into the process's address space, the 
program must not reference display memory or call any of the following vector-drawing 
routines, until the BLT completes: 

SMD_$DRAW_ABS_U 
SMD _ $DRAW _ REL _ U 
SMD _ $MOVE_ ABS _U 
SMD $MOVE REL U 
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Table SMD-1. Display Mode Values 
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Mnemonic 


Meaning 


SMD_$CLRMODE 


Fill destination with a constant. 


SMD $DECR 


Source overlaps destination and x is 




being decremented, that is, destination 




is to right of source . 


SMD $IDONE 


Start BLT and immediately return control 




to calling program. 


SMD_$NONINTERLACE 


Disable hardware interlacing. 


SMD $BLT 


Perform bit BLT operation. Required in 




all calls to SMD_$BLT_U. 



o 
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SMD_$BORROW_DISPLAY_NC_U 

SMD_$BORROW_DISPLAY_NC_U 

Requests use of the display driver and display memory without clearing the screen (black 
and white only). 

FORMAT 

SMD_$BORROW_DISPLAY_NC_U (unit, status) 

INPUT PARAMETERS 

unit 

Unit number of the display to be used. This is a 2-byte integer. Currently, the only valid 
unit number is 1. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$BORROW_ DISPLAY _NC_U requests the use of the display memory and the ^ 

display (SMD) driver routines. A program must execute this routine (or I 

SMD_$BORROW_DISPLAY_U) before it can call any other display driver routines. 

This procedure gains exclusive use of the display for the calling program. The display 
manager continues to operate for all other processes and pads, but the screen does not 
reflect its actions. Control of the screen returns to the display manager when 
SMD_$RETURN_DISPLAY_U is executed, or when you type CTRL/Q. 

To gain access to display memory, call SMD_$MAP_DISPLAY_U. 
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SMD_$BORROW_DISPLAY_U 

SMD_$BORROW_DISPLAY_U 

Requests use of the display driver and display memory, and clears the screen. 

FORMAT 

SMD_$BORROW_DISPLAY_U (unit, status) 

INPUT PARAMETERS 

unit 

Unit number of the display to be used. This is a 2-byte integer. Currently, the only valid 
unit number is 1. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$BORROW_ DISPLAY _U requests the use of the display memory and the display 
driver routines. A program must execute this routine (or 

SMD_$BORROW_DISPLAY_NC_U) before it can call any other display driver 
routines. 

The display is cleared when this procedure is executed. 

SMD_$BORROW_ DISPLAY _NC_U performs an identical borrowing operation, but 
does not clear the screen. 

This procedure gains exclusive use of the Display for the calling program. The Display 
Manager continues to operate for all other processes and pads, but the screen does not 
reflect its actions. Control of the screen returns to the display manager when 
SMD_$RETURN_DISPLAY_U is executed, or when you type CTRL/Q. 

To gain access to display memory, call SMD_$MAP_DISPLAY_U. 
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SMD _ $CLEAR_KBD _ CUKSOR_U 

SMD _$CLEAR_ KBD _ CURSOR _U 

Clears the keyboard cursor from the display. 

FORMAT 

SMD_$CLEAR_KBD_CURSOR_U (status) 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD _$CLEAR_ KBD _ CURSOR _U disables the keyboard cursor and removes it from 
the display. To re-enable the cursor, call SMD _$MOVE_KBD_ CURSOR _U. 
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SMD $CLEAR WINDOW U 



SMD_$CLEAR_WINDOW_U 
Clears an area on the screen. 



FORMAT 



SMD $CLEAR WINDOW U (boundaries, status) 



INPUT PARAMETERS 



o 



boundaries 

The x and y coordinates of the destination area to be cleared, in 

SMD_$WINDOW_LIMITS_T format. This data type is 8 bytes long. In FORTRAN, 
use a four-element array of 2-byte integers. 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD _$CLEAR_ WINDOW _U clears the area of the screen within the boundaries. 

This procedure returns control to its caller after the area is clear. 
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SMD_$COLOR 

SMD_$COLOR 

Sets the color of lines drawn on the display. 

FORMAT 

SMD_$COLOR (color) 

INPUT PARAMETERS 

color 

Either SMD_$WHITE or SMD_$BLACK. This is a 2-byte integer. 

USAGE 

The color set with this call is used in all subsequent vector or box drawing calls executed by 
the program, until another SMD_$COLOR call is executed. 

SMD_$WHITE makes subsequent vectors white or green. SMD_$BLACK makes 
subsequent vectors black. 

This call does not change the color of the background. 



V.. 
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SMD $COND EVENT WAIT U 



SMD_$COND_EVENT_WAIT_U 

Checks an SMD eventcount, but does not wait. 

FORMAT 

SMD_$COND_EVENT_WAIT_U (event-type, event-data, reserved, status) 



O 



o 



o 



OUTPUT PARAMETERS 

event- type 

The type of event that occurred. This is a 2-byte integer. Possible values are 
SMD_$INPUT, SMD _$SCROLL_BLT_ COMPLETE, SMD _$TPAD_ DATA, 
SMD _$TPAD_AND_ INPUT, and SMD _$N0_ EVENT. 

event _ data 

The data associated with the event, in SMD _$EVENT_ DATA _T format. This is a 
2-byte integer. 

reserved 

A 2-byte integer; reserved for future use. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD _$COND_ EVENT _ WAIT _U causes no suspension of the calling program. 
Programs can use this procedure to check for keyboard or touchpad input. 

The only difference between SMD _$COND_ EVENT _ WAIT _U and 

SMD _$EVENT_ WAIT _U is that the first checks the eventcount but does not wait. The 

second waits for an event. 

The SMD_$COND_EVENT_WAIT_U routine returns one type of event 
(SMD_$NO_EVENT) that SMD _$EVENT_ WAIT _U does not. When this type is 
output, it means nothing happened. 
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SMD_$COND_INPUT_U 

SMD _ $COND _ INPUT _ U 

Returns a character if one has been typed. 

FORMAT 

input-flag = SMD_$COND_INPUT_U(char) 

RETURN VALUE 

input-flag 

Boolean (LOGICAL) value. Contains TRUE if a character has been typed and FALSE 
otherwise. 

OUTPUT PARAMETERS 

char 

The character typed at the keyboard. This is a character variable. 

USAGE 

If a character has been typed at the keyboard, the value of this function is TRUE. The 
function returns the character and removes it from the keyboard input buffer. 

If no characters have been typed, the value of the function is FALSE, and the returned char 
parameter is undefined. 



V.. 
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SMD_$DRAW_ABS_U 

SMD _ $DRAW _ ABS _U 

Draws a vector given an absolute position. 

FORMAT 

SMD_$DRAW_ABS_U (column, line) 

INPUT PARAMETERS 

column 

The number of the column to which the vector will be drawn. This is a 2-byte integer in 
the range to 799. 

line 

The number of the line to which the vector will be drawn. This is a 2-byte integer in the 
range to 1023. 

USAGE 

SMD_$DRAW_ABS_U draws a vector from the current position to the point specified 
by (column, line). 

Call SMD_$YECTOR_INIT_U once to initialize the vector drawing package before using 
this procedure. 

No error checking is performed on the arguments, for optimal performance. Incorrect 
program operation occurs if a column or line value is outside the specified range. 

The current position is updated to (column, line) upon completion of this procedure. Use 
SMD_$MOVE_ABS_U or SMD_$MOVE_REL_U to set the position without drawing 
a vector. 
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SMD_$DRAW_BOX_U 

SMD_$DRAW_BOX_U 

Draws a box on the screen. 

FORMAT 

SMD_$DRAW_BOX_U (boundaries, status) 

INPUT PARAMETERS 

boundaries 

The x and y coordinates of the box on the screen, in SMD_$WINDOW_ LIMITS _T 
format. This data type is 8 bytes long. In FORTRAN this is a four-element array of 
2-byte integers. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$DRAW_BOX_U draws lines vertically and horizontally to connect the supplied 
endpoints. 

The supplied values for Xs and Ys must be less than Xe and Ye, respectively. 
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SMD_$DRAW_REL_U 

SMD_$DRAW_REL_U 

Draws a vector given a relative position. 

FORMAT 

SMD_$DRAW_REL_U (column, line) 

INPUT PARAMETERS 

column 

The column number, relative to the current position, to which the vector will be drawn. 
This is a two-byte integer. 

line 

The line number, relative to the current position, to which the vector will be drawn. This 
is a two-byte integer. 

USAGE 

SMD_$DRAW_REL_U draws a vector from the current position to the point computed 
by adding the value of column to the current column and adding the value of line to the 
current line. 

Call SMD_$YECTOR_INIT_U to initialize the vector drawing package before using this 
procedure. 

When the value for column is added to the current position column number, the sum must 
be between and 799 for portrait displays, or between and 1023 for landscape displays. 
Similarly, when the value for line is added to the current position line number, the sum 
must be between and 1023 for portrait displays, or and 799 for landscape displays. 

No error checking is performed on the arguments, for optimal performance. Incorrect 
program operation occurs if a computed column or line value is outside the specified range. 

The current position is updated to the computed column and line values by this procedure. 
Use SMD_$MOVE_REL_U or SMD_$MOVE_ABS_U to set the position without 
drawing a vector. 
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SMD _ $EVENT _ WAIT _U 

SMD_$EVENT_WAIT_U 

Suspends the calling process until you type characters at the keyboard or until the current 
scroll or BLT is complete. 

FORMAT 

SMD_$EVENT_WAIT_U (event-type, event-data, reserved, status) 

OUTPUT PARAMETERS 

event- type 

The type of event that occurred. This is a 2-byte integer. Possible values are the following: 

SMD_$ INPUT 

SMD_$SCROLL_BLT_COMPLETE 
SMD_$TPAD_DATA 
SMD_$TPAD_AND_INPUT 

event- data 

The data associated with the event, in SMD _$EVENT_ DATA _T format. This is a 
2-byte integer. 

reserved 

A 2-byte integer; reserved for future use. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD _$EVENT_ WAIT _U suspends the calling process until a display driver event 
occurs. Programs can use this procedure to read keyboard input. 

An SMD_$INPUT event occurs when you type a character. V^ 

An SMD _$SCROLL_ BLT _ COMPLETE event occurs when a block transfer (BLT) is 
complete, or when the last block transfer required as part of a scrolling operation has been 
started. 

The display driver notifies the calling program of SMD_$INPUT, 
SMD_$SCROLL_BLT_COMPLETE, SMD _$TPAD_ DATA, and 
SMD $TPAD AND INPUT events. 
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SMD_$GET_EC 

SMD_$GET_EC 

Gets the eventcount address of the eventcount that will be advanced upon keyboard input 
or when a BLT is done. 



FORMAT 

SMD_$GET_EC (smd-key, eventcount-pointer. status) 

INPUT PARAMETERS 

smd-key 

This specifies which eventcount to obtain. It is in SMD_$EC_KEY_T format and may 
have a value of either SMD_$INPUT_EC (for the keyboard) or 
SMD_$SCROLL_BLT_EC (for a user-initiated BLT.) This is a 2-byte integer. 

OUTPUT PARAMETERS 

eventcount _ pointer 

The eventcount address to be obtained, in EC2_$PTR_T format. EC2_$PTR_T is a 
pointer to an EC2_$EYENTCOUNT_T. This is a 4-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

The SMD eventcounter is advanced whenever anything is entered via the keyboard and also 
whenever any user-initiated BLT is done. 
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SMD_$INQ_DISP_TYPE 

SMD _ $INQ _DISP _ TYPE 

Returns the type of the display physically attached to the given unit number. 

FORMAT 

display _type = SMD_$INQ_DISP_TYPE (unit) 

RETURN VALUE 

display _ type 

The display configuration in smd_$display_type_t format. This is a 2-byte integer. It 
has one of the following predefined values: 

SMD_$NONE No display 

SMD_$BW_15P Black and white portrait 

SMD_$BW_19L Black and white landscape 

SMD_$COLOR_DISPLAY Color display (1024 x 1024) 

SMD_$800_C0L0R Color display with fewer pixels (1024 x 800) 

SMD_$C0L0R2_DISPLAY Color display (1280x1024x8) 

SMD_$C0L0R3_DISPLAY Color display (1024x800x8) 

SMD_$C0L0R4_DISPLAY Color display (1024x800x4) 

INPUT PARAMETERS 

unit 

This parameter (a 2-byte integer) has three possible meanings, as follows: 

1. The display unit, if the graphics routines are to operate in a borrowed display. 
Currently, the only valid display unit number for borrow-display mode is 1. 

2. The stream identifier for the pad, if the graphics routines are to operate in 
frame or direct mode. Use STREAM _$ID_T format. 

3. Any value, such as zero, if the graphics routines do not use the display. 

USAGE 

Use this call to return the type of the display physically attached to the given unit number. 
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SMD_$LOAD_FONT_FILE_U 
Loads a font file. 

FORMAT 

SMD_$LOAD_FONT_FILE_U (pathname, name-length, font-id, status) 

INPUT PARAMETERS 

pathname 

Pathname, in NAME_$PNAME_T format, of the file containing the font to be loaded. 

name- length 

The number of characters in the pathname. This is a 2-byte integer. 

OUTPUT PARAMETERS 

font- id 

The internal identifier assigned to the font. Font-id is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$LOAD_FONT_FILE_U loads the font in the named file into display memory 
and assigns an identifier to the font. Your program passes the font-id to 
SMD _$WRITE_ STRING to identify the font. 

The images of all loaded fonts coexist in the invisible 28-K byte portion of display memory. 
This area is large enough for about eight small fonts. 

If insufficient space is available in either display memory, or internal tables to load the font, 
SMD _$LOAD_ FONT _ FILE _U returns an error. In this case, your program must 
unload one or more font files to create space for the new font. 

To unload fonts loaded with this routine, use SMD_$UNLOAD_FONT_FILE_U. 

Fonts loaded with this routine are no longer usable when the program exits or aborts. They 
are not, however, unloaded from display memory. 
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SMD _ $LOAD _FONT_U 

SMD_$LOAD_FONT_U 

Loads a font into display memory and returns a font-id. 

FORMAT 

font-id = SMD_$LOAD_F0NT_U (table-ptr. status) 

RETURN VALUE 

font- id 

The internal identifier assigned to the font. This is a two-byte integer. 

INPUT PARAMETERS 

table-ptr 

Address of the font table. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

This function returns an integer font-id. Use the font-id to identify the font in calls to 
SMD _ $WRITE _ STRING _ U. 

FORTRAN programs can use the IADDR function to get an address. Pascal programs can 
use the ADDR function. 

The MS_$MAP call can be used to map a font file prior to using this call. 

The display driver loads the font into any available space in the invisible 28K bytes of 
display memory. This area is large enough for about eight small fonts. 

If insufficient space remains in invisible display memory or for internal tables, an error 
occurs. Your program must then unload one or more fonts to make room for the new one. 

To unload the font, use SMD _$UNLOAD_ FONT _U. 
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SMD_$MAP_DISPLAY_U 

SMD _ $MAP _DISPLAY_U 

Maps display memory into the process' address space. 

FORMAT 

SMD_$MAP_DISPLAY_U (display-address, status) 

OUTPUT PARAMETERS 

display- address 

The address of the first byte of the display memory. Display memory is mapped starting at 
this address, for the next 128-K bytes. This value is in 
SMD_$DISPLAY_MEMORY_PTR_T format. This is a 4-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD _$MAP_ DISPLAY _U creates an association between the display memory and 128-K 
bytes of the calling process' address space. Following this call, your program can directly 
access the display memory by references to the mapped portion of the address space. 

Be careful not to access display memory while a bit BLT is underway. Doing so causes the 
offending program to abort with a hardware bus error fault. To avoid this problem, do not 
include IDONE in calls to SMD_$BLT_U or use SMD _$EVENT_ WAIT _U to wait for 
BLT completion. 

To unmap the display memory, use SMD _$UNMAP_ DISPLAY _U. Display memory is 
automatically unmapped when SMD _$RETURN_ DISPLAY __U is executed, or when you 
type CTRL/Q to exit from the program. 

SMD _$MAP_ DISPLAY __U returns an error status if the display has not been borrowed, 
or if the display is already mapped into the calling process' address space. 
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SMD_$MOVE_ABS_U 

SMD _ $MOVE _ ABS _ U 

Sets the current position for vector drawing. 

FORMAT 

SMD_$MOVE_ABS_U (column, line) 

INPUT PARAMETERS 

column 

The number of the column to which the position is set. This is a 2-byte integer in the range 
through 799. 

line 

The number of the line to which the position is set. This is a 2-byte integer in the range 
through 1023. 

USAGE 

SMD_$MOVE_ABS_U sets the current position, from which the next vector will be 
drawn. 

Call SMD_$VECTOR_INIT_U to initialize the vector drawing package before using this 
procedure. 

No error checking is performed on the arguments, for optimal performance. Incorrect 
program operation occurs if a column or line value is outside the specified range. 
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SMD_$MOVE_KBD_CURSOR_U 

SMD_$MOVE_KBD_CURSOR_U 

Moves the keyboard cursor to a specified position. 

FORMAT 

SMD_$MOVE_KBD_CURSOR_U (position, status) 

INPUT PARAMETERS 

position 

X and y coordinates, in SMD_$POS_T format, for the cursor position. This data type is 
4 bytes long. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$MOVE_KBD_CURSOR_U moves the keyboard cursor to a new position. 

If the cursor was previously removed from the display (via 
SMD_$CLEAR_KBD_CURSOR_U), this call re-enables it. 

In the position parameter, valid line values are 0-1023 for portrait displays, or to 799 for 
landscape displays, and valid column values are 0-799 for portrait displays, or 1023 for 
landscape displays. The values represent the position of the lower left point of the cursor. 

The keyboard cursor is 8 bits wide and 13 bits high. 
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SMD_$MOVE_REL_U 

SMD _ $MOVE_REL _U 

Sets the current position for vector drawing. 

FORMAT 

SMD_$MOVE_REL_U (column, line) 

INPUT PARAMETERS 

column 

The column number, relative to the current position, from which the new column position is 
computed. This is a 2-byte integer. 

line 

The line number, relative to the current position, from which the new line position is 
computed. This is a 2-byte integer. 

USAGE 

SMD_$MOVE_REL_U computes a new position based upon the current value and the 
supplied arguments. 

Call SMD_$VECTOR_INIT_U to initialize the vector drawing package before using this 
procedure. 

When the value for column is added to the current column number, the sum must be 
between and 799 for portrait displays, or between and 1023 for landscape displays. 
Similarly, when the value for line is added to the current line number, the sum must be 
between and 1023 for portrait displays and between and 799 for landscape displays. 

No error checking is performed on the arguments for optimal performance. Incorrect 
program operation occurs if the computed column or line value is outside the specified 
range. 
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SMD _ $OP _ WAIT _ U 

Waits for the current scroll or BLT operation to complete. 

FORMAT 

SMD_$OP_WAIT_U 

USAGE 

SMD _$OP_ WAIT _U waits for completion of the current scroll or BLT operation. When 
this routine returns, the program can safely reference display memory. 

If no scroll or BLT operation is underway, this routine returns immediately. 



SMD- 23 SMD 



SMD _$RETURN_DISPLAY_U 

SMD _ $RETURN _DISPLAY_U 

Returns control of the display to the Display Manager. 

FORMAT 

SMD_$RETURN_DISPLAY_U (unit, status) 

INPUT PARAMETERS 

unit 

Unit number of the display to be returned. This is a 2-byte integer. Currently, the only 
valid unit number is 1. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$RETURN_DISPLAY_U returns control of the display to the Display Manager. 
After executing this procedure, the calling program can no longer use display driver calls. 

If the display was mapped into the process' address space, this procedure unmaps it. 

After execution of this procedure, the Display Manager updates the display to reflect all 
input, output, and scrolling operations that occurred for all pads and processes while the 
screen was under direct program control. 

If SMD_$BORROW_DISPLAY_U has not yet been successfully executed, an error status 
is returned. 



SMD SMD- 24 



SMD_$SET_QUIT_CHAR 



SMD _ $SET_ QUIT_ CHAR 
Defines the quit character. 

FORMAT 

SMD_$SET_QUIT_CHAR (character, status) 

INPUT PARAMETERS 

character 

A single character that is the new quit character. This is a character variable. 

OUTPUT PARAMETERS 

O status 

Completion status, in STATUS_$T format. This data type is 4 bytes long. 

USAGE 

The default quit character is CTRL/Q. 



o 
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SMD_$SET_TP_CURSOR 

SMD_$SET_TP_CURSOR 

Changes normal cursor to touchpad cursor and moves it to the indicated position. 

FORMAT 

SMD_$SET_TP_CURSOR (unit, position, buttons) 

INPUT PARAMETERS 

unit 

A 2-byte integer indicating which display unit to use. Currently, the only valid unit 
number is 1. 

position 

The new position of the cursor, in SMD_$POS_T format. This data type is 4 bytes long. 

buttons 

A 2-byte integer that specifies a combination of buttons according to which bits are set. If 
the bit is set, the corresponding button is down. Following are the bit settings and their 
meanings: 

Bit Position Button 



lefthand button 

1 middle button 

2 righthand button 

3 fourth button 



Given the following assignments: 

unit:= 1; { must always be 1 > 

position. line := 312; 

position. col := 17; 

buttons := 3; < the lefthand button is down > 

the corresponding call would be: 

smd_$set_tp_cursor (unit, position, buttons) 



USAGE 



This call is for use by programs that process data from a locator device other than the 
touch pad, such as a tablet. SMD_$SET_TP_ CURSOR should not be used with the 
touch pad. 

If the keyboard cursor is currently displayed and the touch pad is enabled (see 
SMD_$TP_ENABLE and SMD_$MOVE_KBD_CURSOR_U) executing 
SMD_$SET_TP_ CURSOR removes the keyboard cursor, and displays the touchpad 
cursor at the location denoted by position. 
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SMD_$SOFT_SCROLL_U 

SMD_$SOFT_SCROLL_U 

Starts horizontal or vertical scrolling on the screen, 2 raster lines at a time. 

FORMAT 

SMD_$SOFT_SCROLL_U (boundaries, direction, displacement, status) 

INPUT PARAMETERS 

boundaries 

The x and y coordinates for the edges of the area to be scrolled, in 

SMD_$WINDOW_LIMITS_T format. This data type is 8 bytes long. In FORTRAN 
this is a four-element array of 2-byte integers. 

direction 

Direction in which to scroll in SMD_$DIRECTION_T format. This is a 2-byte integer. 
Possible values are: SMD_$UP, SMD_$DOWN, SMD_$LEFT, and SMD_$RIGHT. 

displacement 

Number of horizontal or vertical raster lines to scroll. This is a 2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$SOFT_ SCROLL _U scrolls two raster lines at a time, until the number of lines 
scrolled is equal to the displacement. 

Scrolling takes place only within the specified area. The rest of the display does not 
change. 

This procedure starts the scrolling operation, then returns control to the calling program. 

Scrolling replicates the two raster lines on the boundary opposite to the direction of 
scrolling (for example, if scrolling up, the two raster lines on the bottom of the scrolled 
area), and does not clear them. Therefore, if you want the scrolling operation to produce 
blank lines, you must make certain the lines that are replicated are blank. You can clear a 
section of the display explicitly using SMD_$CLEAR_ WINDOW. 

Lines scrolled beyond the stated boundaries are lost. 
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SMD_$SOFT_SCROLL_U 

Because scrolling occurs two lines at a time, the display driver can "interlace" other tasks 
with soft scrolling. Thus, the program can call most other display driver routines while 
scrolling is underway. The program must not, however, reference display memory, and it 
must not call any of the following routines: 

SMD_$DRAW_ABS_U 
SMD _ $DRAW _BOX_U 
SMD _ $DRAW _REL _U 
SMD _ $MOVE _ ABS _U 
SMD_$MOVE_REL_U 
SMD _ $RETURN_DISPLAY_U 
SMD $SOFT SCROLL U 



The display driver waits for scrolling to complete before executing one of these procedures. 
Calls to SMD_$BLT_U are executed only if the display mode does not include IDONE. If 
the display mode value includes IDONE, the driver waits for the current scrolling operation 
to complete before starting the BLT. Attempting a BLT with any part of its source or 
destination in the scrolled area is not recommended. 

The program must not reference display memory while scrolling is underway. The program 
can call SMD _$EVENT_ WAIT _U to find out when the completion of scrolling is 
imminent, and can then prepare data for another display operation. After preparing the 
data, the program can call SMD _$OP_ WAIT to wait until references to display memory 
are safe. 
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SMD_$STOP_TP_CURSOR 

SMD _ $STOP _ TP _ CURSOR 

Turns off the touch pad cursor and puts back the blinking cursor, if the blinking cursor 
would otherwise be displayed. 

FORMAT 

SMD_$STOP_TP_CURSOR (unit) 

INPUT PARAMETERS 

unit 

A 2-byte integer indicating which display unit to use. Currently, the only valid unit 
number is 1. 

USAGE 

This call is for use only by programs that process data from a locator device other than the 
touchpad. SMD _$SET_TP_ CURSOR should not be used with the touchpad. 

If the touchpad cursor is currently displayed, it is replaced with the blinking keyboard 
cursor. 
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SMD_$TP_DIRECT 

SMD_$TP_DIRECT 

Controls whether locator device data directly controls the touch pad cursor or is sent to the 
user program. 

FORMAT 

SMD $TP DIRECT (on-off, status) 



INPUT PARAMETERS 

on-off 

A Boolean (logical) variable indicating whether to send the locator device directly to the 
program (TRUE) or to the internal display driver routine that controls the touchpad cursor 
(FALSE). 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

If the value of on-off is FALSE, (the initial state) locator device (for example, touchpad) 
data causes the touchpad cursor to move, as long as the touchpad cursor and keyboard 
cursor are enabled (see SMD _$TP_ DISABLE). Locator device data are delivered through 
SMD _$EVENT_ WAIT as SMD _$TPAD_AND_ INPUT, but only when keystrokes are 
also delivered. 

If the on-off parameter is TRUE, the touchpad cursor is not displayed in response to locator 
device data, and data is delivered in a continuous stream through SMD _$EVENT_ WAIT 
as SMD _ $TP AD _ DATA. 

If the on-off parameter is TRUE, locator data is always delivered, regardless of whether or 
not the touchpad cursor or keyboard cursor is enabled. 
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SMD_$TP_DISABLE 

Prevents locator device data from moving the touchpad cursor. 

FORMAT 

SMD $TP DISABLE (status) 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

This call is for programs that modify display memory directly while the keyboard cursor is 
displayed. The touchpad cursor can interfere with display memory modifications because 
its location is unknown to the user program. SMD _$TP_ DISABLE prevents display of 
the touchpad cursor. 

This call also prevents display of the keyboard cursor if the touchpad has moved it and the 
user program has not yet been given the new position though a 
SMD_$EVENT_WAIT_U call. 

The SMD vector drawing routines modify display memory directly. Therefore, 

SMD _$TP_ DISABLE should be called before calling the vector routines, if the keyboard 

cursor is displayed at the same time the vectors are drawn. 

SMD routines that modify display memory directly, other than the vector drawing routines 
(SMD_$DRAW_REL_U and SMD_$DRAW_ABS_U), automatically disable the 
touchpad cursor when they begin executing and re-enable the cursor when they finish. 

In many cases the keyboard cursor is cleared (removed from the display using 

SMD _$CLEAR_KBD_ CURSOR _U) before display modifications are made. This call is 

not needed in such cases. 

The touchpad cursor is initially disabled. 
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SMD_$TP_ENABLE 

SMD_$TP_ENABLE 

Allows the touch pad cursor to be displayed and moved around the screen. 

FORMAT 

SMD_$TP_ENABLE (status) 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

This call enables display of the touchpad cursor. The touchpad cursor can be disabled by 
calling SMD_$TP_ DISABLE. 

The touchpad cursor is initially disabled. 

In order for the touchpad or other locator device to move the cursor, three conditions must 
be satisfied: 

1. SMD_$MOVE_KBD_ CURSOR must be called to display the cursor in the 
first place. 

2. SMD_$TP_ ENABLE must be called to allow the locator device to affect the 
cursor. 

3. On_off, an input parameter of SMD_$TP_ DIRECT, must be FALSE. (See 
SMD_$TP_DIRECT.) Your program must make explicit calls to satisfy 1 and 
2. The third condition is satisfied by default. 



SMD SMD-32 



o 



o 



o 



o 



SMD_$UNLOAD_FONT_FILE_U 

SMD_$UNLOAD_FONT_FILE_U 

Unloads a font file from display memory. 

FORMAT 

SMD_$UNLOAD_FONT_FILE_U (font- id. status) 

INPUT PARAMETERS 

font- id 

The internal identifier assigned to the font to be unloaded. This 2-byte value is returned by 
SMD _ $LOAD _ FONT _ FILE _ U. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$UNLOAD_FONT_FILE_U unloads a font that was loaded with 

SMD _$LOAD_ FONT _ FILE _U. Following this call, the font is no longer usable in calls 

to SMD _ $WRITE _ STRING. 

An error is returned if the font is not loaded in display memory, or if the associated font 
file is not mapped into the process' address space. 
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SMD_$UNLOAD_FONT_U 

Unloads a font from display memory. 

FORMAT 

SMD_$UNLOAD_FONT_U (font-id. status) 

INPUT PARAMETERS 

font- id 

The internal identifier assigned to the font to be unloaded. This 2-byte value is returned by 
SMD_$LOAD_FONT_U. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

This procedure unloads the specified font, making it unavailable for use. The program 
must reload the font before using it again. 

Use SMD_$UNLOAD_FONT_U for fonts loaded with SMD_$LOAD_FONT_U. Use 
SMD_$UNLOAD_ FONT _ FILE _U for font files loaded with 
SMD $LOAD FONT FILE U. 
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SMD _ $UNMAP _ DISPLAY_ U 

Unmaps display memory from the process' address space. 

FORMAT 

SMD $UNMAP DISPLAY U (status) 



OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

SMD_$UNMAP_DISPLAY_U unmaps the display memory from the calling process' 
address space. Following this call, the 128K-byte portion of the address space onto which 
the display memory was mapped is no longer usable. 

An error status is returned if the display has not been borrowed or if the display memory is 
not mapped when this call is made. 
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SMD_$VECTOR_INIT_U 

SMD_$VECTOR_INIT_U 

Initializes the vector-drawing routines. 

FORMAT 

SMD_$VECTOR_INIT_U (display-address) 

INPUT PARAMETERS 

display- address 

Starting address of the display memory in the program's address space. This is a 4-byte 
integer. This value is returned by SMD_$MAP_ DISPLAY _U. 

USAGE 

SMD_$VECTOR_INIT_U initializes the vector-drawing routines supplied with the 
display driver. These routines are named SMD_$DRAW_ABS_U, 

SMD_$DRAW_REL_U, SMD_$MOVE_ABS_U, and SMD_$MOVE_REL_U. You 
must use SMD_$VECTOR_INIT_U once before calling any vector-drawing routines. 

The vector-drawing routines operate incorrectly if the value of display-address differs from 
that returned by SMD _ $MAP _DISPLAY_U. 

The current position is set to line and column 0. If you call a vector drawing routine 
before calling a position moving routine, the display driver draws a vector from the current 
position. All position-moving and vector-drawing routines update the current position. 
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SMD_$WRITE_ STRING _U 

SMD_$WRITE_STRING_U 

Displays a string of text on the screen. 

FORMAT 

SMD_$WRITE_STRING_U (position, font_id, string, length, waitflag, status) 

INPUT PARAMETERS 

position 

Row and column positions for the first character of the string, in SMD_$POS_T format. 
This data type is 4 bytes long. 

font _ id 

Internal font identifier, returned by SMD_$LOAD_FONT_U. 

string 

String of ASCII text to be displayed. This is an array of up to 120 characters. 

length 

Length, in bytes, of the string to be displayed. This is a 2-byte integer. 

waitflag 

Boolean (logical) value indicating whether to wait for scrolling to complete before displaying 
the string. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. 

USAGE 

This procedure displays a character string on the screen. 

The ordinal (ASCII) value of each character in the input string is used as an index into the font 
denoted by font-id. For instance, the character "A" in the input string causes the output of the 
60th character in the font. If no 60th character is defined in the font, the character "A" is 
ignored. No error occurs and no graphic character is displayed. The cursor is moved to the right 
an amount equal to the size of one space character. 

The position parameter defines the base from which the first character is written. For the 
standard font, valid line values are to 792 and valid column values are 12 to 1019 for a portrait 
display; for a landscape display, valid line values are to 1016 and valid column values are 12 to 
795. 

The ordinal (ASCII) values of the characters in the string must be in the range through 127. 

Set the value of waitflag to TRUE if the string is to be displayed within an area that is being 
scrolled (via SMD_$SOFT_ SCROLL _U) and FALSE otherwise. 
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SMD_$WRITE_ STRING does not clear characters from the portion of the display where the /— \ 

string is written. Since characters may not fill the entire character box, pieces of previous ( 

characters may appear along with the string you wish to write. SMD _$ CLEAR _ WINDOW can ^~^ 

be used to clear a section of the display. 
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ERRORS 

SMD _ $ACCESS _DENIED 

Display borrow request denied by screen manager. 

SMD _ $ALREADY_ ACQUIRED 

Display already acquired. 

SMD _ $ALREADY_ BORROWED 

Display already borrowed by this process. 

SMD _ $ALREADY_MAPPED 

Display memory is already mapped. 

SMD _ $BORROW_ERROR 

Error borrowing display from screen manager. 

SMD _ $CANT _ BORROW _ BOTH 

Cannot borrow both displays simultaneously. 

SMD_$DISP_ACQD 

Pad/stream operations not allowed while display acquired. 

SMD_$DISPLAY_IN_USE 

Unable to borrow: display in use. 

SMD _ $DISPLAY _MAP _ERROR 

Error-mapping display memory. 

SMD _ $FONT _ NOT _ LOADED 

Specified font is not loaded. 

SMD_$FONT_NOT_MAPPED 

Font associated with specified ID is not mapped. 

SMD_$FONT_TABLE_FULL 

Internal font table is full. 

SMD_$FONT_TOO_LARGE 
Font too large. 

SMD_$HDM_FULL 

Hidden display memory is full. 

SMD _ $HDMT _UNLOAD _ERR 

Error unloading internal (HDMT) table. 

SMD _ $ILLEGAL _ CALLER 

Invalid use of display driver procedure. 

SMD _ $ILLEGAL _ DIRECTION 

Invalid direction from SM. 

SMD _ $ILLEGAL _ UNIT 

Invalid display unit number. 

SMD_$INVALID_BLT_COORD 

Invalid screen coordinates in BLT request. 
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SMD _ $INVALID _ BLT _ CTL 

Invalid BLT control register. 

SMD_$INVALID_BLT_MODE 

Invalid BLT mode register. 

SMD _ $INVALID _ BLTD _ INT 

Invalid BLT-done interrupt. 

SMD _ $INVALE) _ BUFFER _ SIZE 
Invalid buffer size. 

SMD _ $INVALID _ CRSR _ NUMBER 
Invalid cursor number. 

SMD _ $INVALID _ DIRECTION 

Invalid direction argument. 

SMD _ $INVALID _ DISPLACEMENT 

Invalid scroll displacement argument. 

SMD _ $INVALID _ ffi. _ STATE 

Invalid interrupt routine state. 

SMD _ $INVALID _KEY 

Invalid eventcount key. 

SMD _ $INVALID _ LENGTH 

Invalid length argument. 

SMD _ $INVALID _POS 

Invalid position argument. 

SMD _ $INVALID _WE> 

Invalid DM window ID. 

SMD _ $INVALID _ WINDOW 

Invalid window limits argument. 

SMD_$NO_MORE_WIDS 

No more direct mode window IDs are available. 

SMD _ $NOT _ BORROWED 

Cannot return: display not borrowed. 

SMD _ $NOT _ IMPLEMENTED 

Nonconforming and main memory BLTs are not implemented. 

SMD_$NOT_MAPPED 

Display memory is not mapped. 

SMD _$NOT_ON_ COLOR 

Operation not implemented on color display. 

SMD_$PROCESS_NOT_FOUND 
Process not found. 

SMD _ $PROTOCOL _ VIOL 

Internal protocol violation. f ^ 
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SMD_$QUIT_WHILE_WAITING 
Quit while waiting. 

SMD_$RETURN_ERROR 

Error returning display to screen manager. 

SMD _ $TOO _MANY_PAGES 

Too many pages to be wired. 

SMD _ $UNEXP _ BLT _ INUSE 

Unexpected BLT in use. 

SMD_$UNSUPPORTED_FONT_VE 

Unsupported font version number. 

SMD _$WAIT_ QUIT 

Quit while waiting. 

SMD _ $WINDOW _ OBSCURED 

Acquire denied because window is obscured. 

STATUS _$OK 

Successful completion. 
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The STREAM (Streams) programming calls perform device-independent I/O. This section 
describes their data types, call syntax, and error codes. Refer to the Introduction at the 
beginning of this manual for a description of data-type diagrams and call syntax format. 
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STREAM DATA TYPES 



CONSTANTS 

STREAM_$MAX 
STREAM_$NO _STREAM 
STREAM_$SUBS 

STREAM_$DIR_ENTTYPE_FILE 

STREAM _ $DIR _ENTTYPE _LINK 

STREAM $DER ENTRY SIZE 



127 



Maximum number of possible stream IDs. 

Place-holder for stream ID when passing streams. 

Subsys component of status return 
denoting streams. 

The file-type value for the enttype field of the 
DIR_ENTRY_T record. 

The link-type value for the enttype field of the 
DIR_ENTRY_T record. 

Size of a directory entry record. 



The following are mnemonic definitions used to specify attributes in the inquire and redefine 
input mask. Attributes followed by an asterisk (*) are attributes to which a stream must be open 
for information to be returned on an inquire. Attributes followed by a plus sign (+) cannot be 
redefined. 



MNEMONIC 

STREAM_$STRID 

STREAM_$OBJ_NAME 

STREAM_$OBJ_NAMLEN 

STREAM_ $REC _LGTH 

STREAM_$TEMPORARY 

STREAM_ $EXPLICIT_TYPE 

STREAM_$AB_FLAG 

STREAM_ $EXPLICIT_ML 

STREAM_$CC 

STREAM_ $REC _ TYPE 

STREAM_$CONC 

STREAM_$OCONC 

STREAM_$OPOS 

STREAM_$PRE_EXIST 

STREAM_ $HDR _LGTH 

STREAM $FILE LGTH 



Bit 



1 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 



Explanation 
Stream ED. + 
Object name. 
Object name length. 
Record length. 
Temporary or permanent. * 
Explicit record type. 
ASCII or binary file. 
Explicit move mode. * 
Carriage control. 
Record type. 
Object concurrency. 
Concurrency at open. * 
Access type. * 
Pre-existing object. -f- 
Header length. + 
File length. + 
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STREAM_ $SEEK_KEY 


15 


STREAM_$CUR_REC_LEN 


16 


STREAM_$CUR_REL_REC_NO 


17 


STREAM_$BLKS_USED 


18 


STREAM_$DTU 


19 


STREAM_$DTM 


20 


STREAM_$SPARSE 


21 


STREAM_$OTYPE 


22 


STREAM_$CLOSE_ON_EXEC 


23 


STREAM_$NDELAY 


24 


STREAM_ SAPPEND _MODE 


25 


STREAM_$FORCED_LOCATE 


26 


DATA TYPES 





STREAM $PARM1 T 



Seek key. * + 

Current record length. * + 

Current relative record number. * + 

Number of blocks used. + 

Date and time last used. + 

Date and time last modified. + 

Sparsely written file. * + 

Object type. 

Close stream on DOMAIN/DC Exec call. 

Forced STREAM _$GET_ CONDITIONAL. 

File in append mode. 

Force locate mode. 



O 



A 2-byte integer. Specifies the type of data on 
which the seek is being performed. One of the 
following predefined values: 

STREAM _$KEY 

Seek with key returned earlier by stream 

manager. 

STREAM_$REC 
Record-oriented seek. 
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STREAM $PARM2 T 



STREAM_$CHR 
Character-oriented seek. 

STREAM_$EOF 

Seek to the end-of-file. 

A 2-byte integer. Specifies the type of seek being 
performed. One of the following predefined values: 

STREAM_ $RELATr/E 

Seek relative to current position. 

STREAM_ $ABSOLUTE 

Seek relative to BOF or EOF. 
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STREAM $OPOS T 



A 2-byte integer. Specifies the access type of an 
object on open/create. One of the following 
predefined values: 



STREAM_$READ 

Open/create for read-only access. 

STREAM_$WRITE 

Create (new) for write access. 

STREAM_$OVERWRITE 

Write access; truncate file to BOF if it 

already exists. 

STREAM_$UPDATE 

Write access; file may already exist; position 

to start of file on open. 

STREAM_$APPEND 

Write access; if file already exists, position to 

EOF on open. 

STREAM_ $MAKE_BACKUP 

Create new file: rename existing file to .BAK 

on close. 



STREAM $OMODE T 



A 2-byte integer. Specifies the concurrency at open 
of an object. One of the following predefined 
values: 



STREAM_ $NO _ CONC _ WRITE 

Allows no concurrent writers to open file 

while this stream is open. 

STREAM_ $CONTROLLED _ SHARING 

Currently the same as NO _ CONC _ WRITE. 

STREAM_ $REGULATED 

Allows unrestricted reading and writing of the 

file. 
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STREAM $FCONC T 



A 2-byte integer. Specifies the object concurrency. 
One of the following predefined values: 



STREAM_$N_OR_l 

Allows N readers or 1 writer in file 

concurrently. 

STREAM_ $N_ AND __ 1 

Allows N readers AND up to 1 writer 

concurrently. 
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STREAM_$N_AND_N 

Allows any number of writers or readers 

concurrently. 



STREAM $CC T 



STREAM_$STRICT_N_0R_1 

Disallows multiple writers even when they are 

in a process family. 

A 2-byte integer. Specifies the type of carriage 
control employed in the object. One of the 
following predefined values: 



STREAM_$CC_T 

ASCII ("Apollo standard") carriage control. 



STREAM $RTYPE T 



STREAM_$F&&_CC 

Fortran-77 standard (column l) carriage 

control. 

A 2-byte integer. Specifies the record structure of 
the object. One of the following predefined values: 



STREAM_$V1 

Variable length records with count fields. 
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STREAM_$F2 
Fixed-length records. 

STREAM_$UNDEF 

No record structure in data. 



STREAM $IR OPT 



A 2-byte integer. Specifies method for accessing 
attribute record. One of the following predefined 
values: 



o 



STREAM_$USE_STRID 

Use the stream-id to access the attribute 

record. 

STREAM_ $NAME_ CONDITIONAL 

Inquire is about the filename; only return 

information if file is open. 

STREAM_ $NAME_UNCONDITIONAL 

Use the filename to access the attribute block. 



STREAM_$INQUIRE_MASK_T 



A 2-byte integer. Attributes to inquire. Specify any 
combination of the mnemonic constants for object 
attributes. 



STREAM $REDEF MASK T 



A 2-byte integer. Attributes to redefine. Specify any 
combination of the valid mnemonic constants for 
object attributes. 
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STREAM $EC KEY T 



A 2-byte integer. Specifies an eventcount to get. 
One of the following predefined values: 

STREAM_ $GETREC _EC _KEY 
Stream eventcount key. 

STREAM_$EDIT_WAIT_EC_KEY 
Edit pad eventcount key. 



STREAM $OPEN OPTIONS T 



STREAM $OPEN OPTIONS SET T 



STREAM $IR REC T 



STREAM $ID T 



A 2-byte integer. Options available at open time. 
One of the following predefined values: 

STREAM_ $NO _DELAY 

Do not wait for I/O (currently applies only to 

opening pipes). 

A 2-byte integer. Options available at open time 
with the STREAM_$OPEN_OPT call. Currently 
the only option available is: 

STREAM_ $NO _DELAY 

Do not wait for I/O (currently applies only to 

opening pipes). 

Attribute record for INQUIRE and REDEFINE 
calls. The streams chapter of the Programming 
With General System Calls manual describes how 
to use the attribute record. The diagram below 
illustrates the STREAM _$IR_ REC _T data type: 

A 2-byte integer. Open stream identifier. 
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STREAM $SK T 



Seek key returned on most stream calls. The 
diagram below illustrates the STREAM _$SK_T 
data type: 



o 



predefined 
type 



byte: 
offset 




field name 


0: 


integer 


rec_adr 


4: 


integer 


byte_adr 


8: 


integer 


flags 




Field Description: 

rec_adr 

The address of the record sought. 



byte_adr 

The address of the byte sought. 



O 



predefined 
type 



flags 

Flags containing seek information. 



byte: 
offset 


31 C 


field name 
) 


0: 


integer 


offset 




Field Description: 





offset 

The offset of the record or character sought. 
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predefined 
type 


byte 
ofrs( 



2 

4 

8 

10 

12 

14 

16 

20 

24 
28 
32 
36 
40 
44 
48 
52 
56 
60 
62 
64 
68 

n 


3t 






stream_$id_t 


: integer 






integer 




integer 




integer 






integer 




integer 




integer 




integer 




integer 


stream_$sk_t 


integer 




integer 




integer 




integer 




integer 


time_$clockh_t 


integer 


time_$clockh_t 


integer 


uid_$t 


integer 


integer 




integer 






integer 




integer 




char 




name_$name_t 


* * 




: char 


* 



field name 

strid 

obj_namlen 

recjgth 

flagsl * 

flags2* 

unused 

hdrjgth 

filejgth 

seek_key . rec_adr 

seek_key . byte_adr 

seek_key. flags 

cur_rec_len 

cur_rel_rec_no 

blks_used 

dtu 

dtm 

otype.high 

otype.low 

flags3* 

flags4* 

unused 

obj_name 

see below for field names 



Field Description: 

strid 

The stream ID of the object. 

obj _ namlen 

The length of the object's name. 
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rec_lgth 

The length of the longest record in the object. 

flags 1 

A bit mask containing predefined or Boolean 
values indicating object attributes. The 
following table lists the bit numbers within the 
mask, the record field names, and a short 
decription of each attribute: 

Bit # Field Name Description 

Bit temporary Temporary 

or 

permanent 
object 

Bit 1 explicit_type Explicit 

fixed- 
length 
records 

Bit 2 ab_flag ASCII or 

binary 
file 

Bit 3 explicit_ml Explicit 

move mode 

Bit 4-5 unusedl 

Bit 6 cc Type of 

carriage 
control 

Bit 7-9 unused2 

Bit 10-11 rec_type Record type 

Bit 12-13 unused3 

Bit 14-15 cone Object 

concurrency 

flags2 

A bit mask containing predefined or Boolean 
values indicating object attributes. The 
following table lists the bit numbers within the 
mask, the record field names, and a short 
decription of each attribute: 

Bit # Field Name Description 



Bit 


0-1 


unused4 




Bit 


2-3 


oconc 


Concurrency 


Bit 


4-5 


unused5 


at open 


Bit 
Bit 


6-8 
9 


opos 
pre_exist 


Access type 
Pre- 
existing 
object 



Bit 10-15 unused6 

hdr__lgth 

The length of the object header. 
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file_lgth 

The length of the file. 

seek _ key 

The current seek-key. 

cur_rec_len 

The length of the current record. 

cur _ rel _ rec _ no 

The current record number relative to BOF. 

blks_used 

The number of blocks occupied by the file. 

dtu 

The date and time of the last use of the object. 

dtm 

The date and time of the modification of the 

object. 

otype 

Specifies the type of the object. 

flags3 

A bit mask containing predefined or Boolean 
values indicating object attributes. The 
following table lists the bit numbers within the 
mask, the record field names, and a short 
decription of each attribute: 

Bit # Field Name Description 

Bit sparse File may 

contain 
"holes." 

Bit 1-15 unused7 

flags4 

A bit mask containing predefined or Boolean 
values indicating object attributes. The 
following table lists the bit numbers within the 
mask, the record field names, and a short 
decription of each attribute: 

Bit jf Field Name Description 

Bit 0-12 unused8 

Bit 13 close_on_exec Close stream 

on UNIX Exec 

call 
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Bit 


14 


ndelay Forced 
STREAM $GET CONDITIONAL 


Bit 


25 


append_mode File in 

append mode 


Bit 


26 


forced locate Force 



locate mode 



STREAM $DIR ENTRY T 



obj _ name 

The name of the object. 

The directory entry returned by 
STREAM_$GET_REC. The diagram below 
illustrates the STREAM _$DIR_ENTRY_T data 
type: 



o 



o 



predefined 
type 


byte: 
offset 

0: 

2: 

• 

4: 

36: 
40: 


15 


C 


I 


field name 




integer 




enttype 




integer 


entlen 




char 






entname 


iame_$pname_t 


* * 








integer 


unusedl 




integer 


unused2 



o 



Field Description: 

enttype 

Type of the directory entry. Either 

NAME $FILE or NAME $LINK. 



entlen 

Length of the directory entry name. 

entname 

Name of the directory entry. 
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O 



unusedn 

Reserved for future use by Apollo. 

A 2-byte integer. Options available for force 
writing to disk. Any combination of the following 
predefined values: 

STREAM_$FW_FILE 

Specifies that a file should be force- written. 
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STREAM_$FW_DIR 

Specifies that the directory of the file should 

be force-written. 



STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


1 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 



STREAM 
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STREAM_$CLOSE 

STREAM_$CLOSE 
Closes a stream. 

FORMAT 

STREAM_$CLOSE (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of the stream to be closed, in STREAM_$ID_T format. This is a 2-byte integer. 

The number used for stream identification becomes available for reuse. If the object is open 
on more than one stream, STREAM_$ CLOSE closes only the specified stream. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM _$CLOSE closes the stream, so that you can no longer use the stream-id to 
operate on the object. Closing a stream to an object releases any locks maintained for the 
current user and may thus make the object available to other users. 

If the stream is a disk file opened for any type of write access (STREAM_$WRITE, 
STREAM_$OVERWRITE, S TRE AM _$ APPEND, or STREAM _$UPDATE), 
STREAM_$CLOSE updates its header, reflecting any changes made to the file while it was 
open, and indicating the date and time of last use and modification. 

A program can close only the streams it has opened, and those opened by programs it has 
invoked (that is, opened at lower levels). Trying to close a stream opened at a higher level 
produces an error status code. 

Closing a temporary object deletes it if no other process is using it. 
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STREAM_$CREATE 

STREAM_$CREATE 

Creates an object (if the object does not already exist) and opens a stream to it. 

FORMAT 

STREAM_$CREATE (pathname, name-length, access, concurrency, stream-id, status) 

INPUT PARAMETERS 

pathname 

Name of the object to be created, in NAME_$PNAME_T format. This is a character 
array of up to 256 elements. 

name- length 

Length of the pathname, in bytes. This is a 2-byte integer. To create a temporary object, 
specify a length of 0. 

access 

Type of access requested, in STREAM_$OPOS_T format. Possible values are: 

STREAM _ $APPEND 

Permits adding data to the end of an object. The stream pointer points 
to the end of the object (EOF). 

STREAM_$MAKE_BACKUP 

Creates a temporary file, with the same type and attributes as the file -_, 

specified in the pathname. This access is used to create a backup file. ( 

(See below for a detailed description.) ^~ 

STREAM _ $OVERWRITE 

Permits replacing the entire contents of an object. The stream pointer is 
positioned at the start of the object data and data is truncated. 

STREAM_$READ 

Permits reading data from an existing object. 

STREAM_$UPDATE 

Permits replacing selected portions of the contents of an object. The 
stream pointer is positioned at the start of the object data, just past the 
header if it has one. 

STREAM_$WRITE 

Permits writing data to a new object. If writing is attempted on an 
existing object, an error status is returned. 

If you specify the access option STREAM _$ WRITE, the pathname must refer to a new 
object; otherwise, an error status is returned. 

If you specify the access option STREAM _$MAKE_ BACKUP, a new, unnamed 
temporary file is created by this call, which has the same type and other attributes as the 
file given by the pathname (if it exists). The new file is created on the same volume (i.e. 
the same node) as the file given by the pathname. The file given by the pathname is not 
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STREAM_$CREATE 

opened or modified in this case, but is examined to extract its attributes. Even though the 
existing file is not modified, it is conceptually being replaced, so this operation requires 
write access to the file. 

The application then writes the new file, and when it is closed (by the STREAM_$CLOSE 
call) the name of the file given at create time is changed to pathname. BAK. The new 
(formerly unnamed temporary) file gets the old name, and becomes permanent. 

If the ".bak" file already exists, it is deleted. (The caller must have either D or P rights to 
delete the file.) If the ".bak" file is locked at the time STREAM_$CLOSE is called, it is 
deleted when it is unlocked. 

If the pathname mentioned in the create call does not exist, then an ordinary 

STREAM _$CREATE is done, as though the access option had been STREAM_$WRITE 

instead of STREAM_$MAKE_ BACKUP. 

concurrency 

Requested concurrency at open, in STREAM _$OMODE_T format. Possible values are: 

STREAM _ $CONTROLLED _ SHARING 
No concurrent writing. 

STREAM_$NO_CONC_WRITE 

No concurrent writing. 

STREAM _ $UNREGULATED 

Unregulated read and write access. 

OUTPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in STREAM _$ID_T format. This is a 
2-byte integer. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

If the pathname specifies an object that does not exist, the stream manager creates a new 
UASC disk file with that pathname and opens a stream to it. 

If the pathname specifies an existing object, the stream manager opens a stream to it for 
overwrite, update, or append access. If write access is specified for an existing object, an 
error status is returned. 

STREAM_$ CREATE can open existing objects of any type, but can create only disk files. 
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Default attributes for a new disk file are listed below: 
Attribute Default Value 

Data type ASCII 

Record type UASC file format 

Location Lowest level in the directory pathname. If no pathname is specified, 

assume the current working directory. 

Concurrency No default. 

Object concurrency 

One writer or any number of readers. 

Carriage control DOMAIN standard. 

If the object already exists, its attributes remain the same when it is opened. For streams 
to serial lines, however, "cooked" input mode and NO_WAIT are always in effect when 
the stream is opened. To change the object's attributes, call STREAM _$REDEFINE (or 
SIO_$CONTROL) before writing the object. 

Both STREAM _$CREATE and STREAM _$OPEN open a stream to an object. However, 
STREAM _$CREATE creates the object if it does not exist, whereas STREAM _$OPEN 
returns an error if the object does not exist. 



V 
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STREAM_$CREATE_BIN 

STREAM_$CREATE_BIN 

Creates a binary record-structured file (if the file does not already exist) and opens a stream 
to it. 



FORMAT 

STREAM_$CREATE_BIN (pathname, name-length, access, concurrency, stream-id, 
status) 

INPUT PARAMETERS 

pathname 

Name of the object to be created, in NAME_$PNAME_T format. This is a character 
array of up to 256 elements. 

name- length 

Length of the pathname, in bytes. This is a 2-byte integer. To create a temporary object, 
specify a length of 0. 

access 

Type of access requested, in STREAM_$OPOS_T format. Possible values are: 

STREAM _ $APPEND 

Permits adding data to the end of an object. The stream pointer points 
to the end of the object (EOF). 

STREAM_$MAKE_BACKUP 

Creates a temporary file, with the same type and attributes as the file 
specified in the pathname. This access is used to create a backup file. 
(See below for a detailed description.) 

STREAM _ $OVERWRITE 

Permits replacing the entire contents of an object. The stream pointer is 
positioned at the start of the object data and data is truncated. 

STREAM _$READ 

Permits reading data from an existing object. 

STREAM _ $UPDATE 

Permits replacing selected portions of the contents of an object. The 
stream pointer is positioned at the start of the object data, just past the 
header if it has one. 

STREAM_$WRITE 

Permits writing data to a new object. If writing is attempted on an 
existing object, an error status is returned. 

If you specify the access option STREAM_$ WRITE, the pathname must refer to a new 
object; otherwise, an error status is returned. 

If you specify the access option STREAM _$MAKE_ BACKUP, a new, unnamed 
temporary file is created by this call, which has the same type and other attributes as the 



STREAM- 17 STREAM 



STREAM_$CREATE_BIN 

file given by the pathname (if it exists). The new file is created on the same volume (i.e. 

the same node) as the file given by the pathname. The file given by the pathname is not ( 

opened or modified in this case, but is examined to extract its attributes. Even though the — ^ 

existing file is not modified, it is conceptually being replaced, so this operation requires 

write access to the file. 

The application then writes the new file, and when it is closed (by the STREAM_$CLOSE 
call) the name of the file given at create time is changed to pathname.BAK. The new 
(formerly unnamed temporary) file gets the old name, and becomes permanent. 

If the " .bak" file already exists, it is deleted. (The caller must have either D or P rights to 
delete the file.) If the ".bak" file is locked at the time STREAM_$CLOSE is called, it is 
deleted when it is unlocked. 

If the pathname mentioned in the create call does not exist, then an ordinary 
STREAM _$CREATE_ BIN is done, as though the access option had been 
STREAM_$WRITE instead of STREAM _$MAKE_ BACKUP. 

concurrency 

Requested concurrency at open, in STREAM _$OMODE_T format. Possible values are: 

STREAM _ $CONTROLLED _ SHARING 
No concurrent writing. 

STREAM_ $NO _ CONC _ WRITE 

No concurrent writing. 

STREAM_ $UNREGULATED 

Unregulated read and write access. 

OUTPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in STREAM _$ED_T format. This is a 
2-byte integer. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

If the named object does not exist, the stream manager creates a binary file of fixed length 
records and opens a stream to it. 

If the named object already exists, the file attributes remain the same and the stream 
manager opens a stream to it for overwrite, update, or append access. If write access is 
specified for an existing object, an error status is returned. 

To change the file's attributes, call STREAM _$REDEFINE (or SIO_$CONTROL) before 
writing the object. 

Both STREAM_$CREATE_BIN and STREAM _$OPEN open a stream to a file. 
However, STREAM _$CREATE_ BIN creates the file if it does not exist, whereas 
STREAM $OPEN returns an error if the file does not exist. 
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STREAM_$CREATE_BIN differs from STREAM _$CREATE in that 
STREAM _$CREATE creates a UASC file by default. 



o 



o 
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STREAM_$CREATE_HERE 

Creates an object at the specified location and opens a stream to it. 

FORMAT 

STREAM_$CREATE_HERE (pathname, name-length, access, concurrency, 

loclen, locname, stream-id, status) 

INPUT PARAMETERS 

pathname 

Name of the object to be created, in NAME_$PNAME_T format. This is a character 
array of up to 256 elements. 

name- length 

Length of the pathname, in bytes. This is a 2-byte integer. To create a temporary object, 
specify a length of 0. 

access 

Type of access requested, in STREAM_$OPOS_T format. Possible values are: 

STREAM _ $ APPEND 

Permits adding data to the end of an object. The stream pointer points 
to the end of the object (EOF). 

STREAM_ $MAKE_BACKUP 

Creates a temporary file, with the same type and attributes as the file 
specified in the pathname. This access is used to create a backup file. 
(See below for a detailed description.) 

STREAM_ $OVERWRITE 

Permits replacing the entire contents of an object. The stream pointer is 
positioned at the start of the object data and data is truncated. 

STREAM _$READ 

Permits reading data from an existing object. 

STREAM _ $UPDATE 

Permits replacing selected portions of the contents of an object. The 
stream pointer is positioned at the start of the object data, just past the 
header if it has one. 

STREAM_$WRITE 

Permits writing data to a new object. If writing is attempted on an 
existing object, an error status is returned. 

If you specify the access option STREAM _$ WRITE, the pathname must refer to a new 
object; otherwise, an error status is returned. 

If you specify the access option STREAM_$MAKE_ BACKUP, a new, unnamed 
temporary file is created by this call, which has the same type and other attributes as the 
file given by the pathname (if it exists). The new file is created on the same volume (i.e. 
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the same node) as the file given by the pathname. The file given by the pathname is not 
opened or modified in this case, but is examined to extract its attributes. Even though the 
existing file is not modified, it is conceptually being replaced, so this operation requires 
write access to the file. 

The application then writes the new file, and when it is closed (by the STREAM_$ CLOSE 
call) the name of the file given at create time is changed to pathname. BAK. The new 
(formerly unnamed temporary) file gets the old name, and becomes permanent. 

If the " .bak" file already exists, it is deleted. (The caller must have either D or P rights to 
delete the file.) If the ".bak" file is locked at the time STREAM_$CLOSE is called, it is 
deleted when it is unlocked. 

If the pathname mentioned in the create call does not exist, then an ordinary 
STREAM _$CREATE_ HERE is done, as though the access option had been 
STREAM_$WRITE instead of STREAM _$MAKE_ BACKUP. 

concurrency 

Requested concurrency at open, in STREAM_$OMODE_T format. Possible values are: 

STREAM_$CONTROLLED _SHARING 
No concurrent writing. 

STREAM_$NO_CONC_WRITE 

No concurrent writing. 

STREAM _ $UNREGULATED 

Unregulated read and write access. 

loclen 

Length of locname, in bytes. This is a 2-byte integer. 

locname 

Location at which to create the object, in NAME_$PNAME_T format. This is a 
character array of up to 256 elements. 

The location can be a tree name or a leaf name. 



OUTPUT PARAMETERS 

stream- id 

Number of the stream on which the object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 



USAGE 



This call creates an object at a specified location. It is especially useful for creating a 
temporary file on the same logical volume as an existing object. 

If the pathname specifies an object that does not exist, the locname must specify the parent 
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directory for the new object. If the pathname specifies an existing object, the locname and 
loclen are ignored. 

If both the object and the location pathnames are valid, the stream manager opens a stream 
to the object for overwrite, update, or append access. If write access is specified for an 
existing object, an error status is returned. 

STREAM _$ CREATE _ HERE can open existing objects of any type, but can create only 
disk files. 

Both STREAM_$CREATE_HERE and STREAM_$OPEN open a stream to an object. 
STREAM _$CREATE_ HERE, like STREAM _$CREATE, creates the object if it does 
not exist, whereas STREAM_$OPEN returns an error if the object does not exist. 
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STREAM_$DELETE 

Deletes an object and closes the associated stream. 

FORMAT 

STREAM_$DELETE (stream-id, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

An error occurs if the stream is open for read access only. 
An error status is returned if the stream is not open. 

USAGE 

STREAM _$DELETE deletes the object, then closes the specified stream. 

If the object cannot be deleted, an error occurs and all streams associated with the object 
remain open. Input pads cannot be deleted. 

If the object is open on more than one stream, STREAM _$DELETE deletes the object 
causing "object deleted" errors when other streams try to read or write the object. 

Files or pads are deleted immediately, even if several processes have opened the object. 

For serial lines and magnetic tape files, this call operates exactly like STREAM_$CLOSE. 
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STREAM_$FORCE_WRITE_FILE 

Forcibly writes a disk file open on the given stream. 

FORMAT 

STREAM_$FORCE_WRITE_FILE (stream-id. options, status) 

INPUT PARAMETERS 

stream- id 

The number of the stream on which the disk file is open, in STREAM_$ID__T format. 
This is a 2-byte integer. 

options 

The object types to be force-written, in STREAM_$FORCE_WRITE_OPTIONS_T 

format. Possible values are: ^- 

STREAM_$FW_FILE L. 

Forces the file to disk. 

STREAM_$FW_DIR 

Forces the file's directory to disk. 

OUTPUT PARAMETERS 

status I 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

Programs can call S TREAM_$FORCE_ WRITE _ FILE to ensure that the file is stored on 
disk before it is closed. 

If a program is handling a critical file, it can call this routine on the open stream to f 

force-write the file's directory, thereby ensuring that the file pointer is saved in the V_ 

directory. 
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STREAM_$GET_BUF 

Reads data from an object into a specified buffer. 

FORMAT 

STREAM_$GET_BUF ( stream- id. bufptr. buflen, retptr, retlen, seek-key, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

bufptr 

Pointer to the buffer into which the data may be read, in UNIV_PTR format. This is a 
4-byte integer. 

To obtain a value for bufptr, FORTRAN programs can use the IADDR function. Pascal 
programs can use the ADDR function. The buffer can be aligned on a byte boundary; 
therefore, the value of bufptr can be odd. 

buflen 

Number of bytes of data to be read. This is a 4-byte integer. 

OUTPUT PARAMETERS 

retptr 

Pointer to the data returned, in UNTV_PTR format. This is a 4-byte integer. 

Address the returned data only by using retptr. The stream manager may use "locate 
mode," in which it doesn't copy the desired data to the location indicated by bufptr. 
FORTRAN programs that call the stream manager in locate mode should use the "pointer 
variable" FORTRAN extension. 

The value of retptr is meaningful only until execution of the next stream call on this 
stream. 

retlen 

Number of bytes of data returned. This is a 4-byte integer. 

seek- key 

Unique key identifying the location of the data read, in STREAM _$SK_T format. This 
is a three-element array of 4-byte integers. 

To obtain a seek-key value for the current stream position, call STREAM _$ GET _BUF 
with a buflen of 0. 

If the returned status is nonzero, the seek-key may not be useful. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 
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USAGE 



For UASC files, STREAM _$ GET _ BUF returns the requested number of bytes, including 
newline characters. UASC file records are delimited by the line-feed character (16#0A). 

For non-UASC files, STREAM _$GET_ BUF functions the same as 
STREAM_$GET_REC. That is, for fixed- or variable-length records 
STREAM _$GET_ BUF returns one record, and for nonrecord-structured files 
STREAM _$ GET _ BUF returns the requested number of characters. 

FORTRAN programs using this procedure in locate mode should use the pointer variable 
FORTRAN extension. Otherwise, call STREAM _$REDEFINE to set move mode before 
using this procedure. 
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STREAM _ $GET _ CONDITIONAL 

Reads a record if the record is available; otherwise, it sets the returned record length to 
zero. 



FORMAT 

STREAM_$GET_CONDITIONAL (stream-id. bufptr. buflen, retptr, retlen. 

seek-key, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM _$ID_T format. This is a 
2-byte integer. 

bufptr 

Pointer to the buffer into which the data may be read, in UNIV_PTR format. This is a 
4-byte integer. 

To obtain a value for bufptr, FORTRAN programs can use the IADDR function. Pascal 
programs can use the ADDR function. The buffer can be aligned on a byte boundary; 
therefore, the value of bufptr can be odd. 

buflen 

Number of bytes of data requested. This is a 4-byte integer. 

If the number of bytes remaining in the record is less than buflen, 

STREAM_$GET_ CONDITIONAL returns the remainder of the record. If the number of 
bytes remaining in the record is greater than buflen, the stream manager reads enough data 
to fill the buffer and returns a negative value in retlen. The absolute value of retlen is the 
number of bytes remaining in the record. 

OUTPUT PARAMETERS 

retptr 

Pointer to the data returned, in UNIV_PTR format. This is a 4-byte integer. 

Address the returned data only by using retptr. The stream manager may use "locate 
mode," in which it doesn't copy the desired data to the location indicated by bufptr. 
FORTRAN programs that call the stream manager in locate mode should use the "pointer 
variable" FORTRAN extension. 

Records are aligned on word boundaries. Therefore, if the procedure reads an entire record, 
the value of retptr will be word-aligned and positive. The value of retptr is meaningful 
only until execution of the next stream call for this stream. 
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retlen 

Number of bytes of data actually returned. This is a 4-byte integer. 

If the call returned any data, retlen has a value equal to the requested number of bytes. It 
has a value of if the call returned no data. 

seek- key 

Unique key identifying the location of the data returned, in STREAM_$SK_T format. 
This is a three-element array of 4-byte integers. 

If the returned status is nonzero, the seek-key is not useful. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM_$GET_ CONDITIONAL performs read operations on streams such as SIO lines, 
input pads, and mailboxes, for which data may not yet be available at the time of the call. 
Under these conditions, STREAM _$ GET _REC waits for data. 

STREAM _$GET_ CONDITIONAL never waits. If data is not immediately available, it 
returns a length of zero. 

This call is commonly used in conjunction with STREAM _$GET_ EC and EC2_$WAIT. 

Since data from ordinary files is always available, this call is equivalent to 
STREAM_$GET_REC for files. 

No error occurs if the stream manager cannot find data at the current stream position, 
unless the current position is known to be at EOF. In this case, a zero is returned in retlen. 
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STREAM_$GET_EC 

Gets the eventcount address of the eventcount to be advanced upon any activity within the 
specified stream. 

FORMAT 

STREAM_$GET_EC (stream-id. stream-key, eventcount-pointer, status) 

INPUT PARAMETERS 

stream- id 

The stream ID, in STREAM _$ID_T format. This is a 2-byte integer. 

stream- key 

The key that specifies which eventcount to get, in STREAM_$EC_KEY_T format. The 
only value allowed is STREAM_$GETREC_EC_KEY. 

OUTPUT PARAMETERS 

eventcount-pointer 

The eventcount address to be obtained, in EC2_$PTR_T format. EC2_$PTR_T is a 
pointer to an EC2 _ $EVENTCOUNT _ T array. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

The eventcount is advanced whenever data becomes available through the stream. This call 
is valid for all streams, including those open to files, pads, mailboxes, and COMMENTs. 

If the input pad is in raw mode then an event is counted after each single character stroke; 
if the keyboard is in cooked mode then an event is counted after each carriage return. 

See the description of EC2_$WAIT for a description of eventcount data structures. See 
Programming With General System Calls for a discussion of eventcounts. 
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STREAM_$GET_PRIOR_REC 
Reads the previous record. 

FORMAT 

STREAM_$GET_PRIOR_REC (stream-id, bufptr, buflen, retptr, retlen, 

seek-key, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM_$ID__T format. This is a 
2-byte integer. 

bufptr 

Pointer to the buffer into which the data may be read, in UNIV_PTR format. This is a 
4-byte integer. 

To obtain a value for bufptr, FORTRAN programs can use the IADDR function. Pascal 
programs can use the ADDR function. The buffer can be aligned on a byte boundary; 
therefore, the value of bufptr can be odd. 

buflen 

Number of bytes of data requested. This is a 4-byte integer. 

If the number of bytes remaining in the record is less than buflen, 

STREAM _$GET_ PRIOR _REC returns the remainder of the record. The value returned 
in retlen is the number of bytes actually read. If the number of bytes remaining in the 
record is greater than buflen, the stream manager reads enough data to fill the buffer and 
returns a negative value in retlen. The absolute value of the returned retlen is the number 
of bytes remaining in the record. 

OUTPUT PARAMETERS 

retptr 

Pointer to the data returned, in UNTV_PTR format. This is a 4-byte integer. 

Address the returned data only by using retptr. The stream manager may use "locate 
mode," in which it doesn't copy the desired data to the location indicated by bufptr. 
FORTRAN programs that call the stream manager in locate mode should use the "pointer 
variable" FORTRAN extension. 

Records are aligned on word boundaries. Therefore, if the procedure reads an entire record, 
the value of retptr will be word-aligned and positive. The value of retptr is meaningful 
only until execution of the next stream call on this stream. 

retlen 

Number of bytes of data returned. This is a 4-byte integer. 

If the number of bytes remaining in the record is less than buflen, 

STREAM_$GET_PRIOR_REO returns the remainder of the record. The value of retlen 
is the number of bytes actually read. 
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If the number of bytes remaining in the record is greater than buflen, the stream manager 
reads enough data to fill the buffer and returns a negative value in retlen. The absolute 
value of the returned retlen is the number of unread bytes remaining in the record. 

seek- key 

Unique key identifying the location of the data returned, in STREAM_$SK_T format. 
This is a three- element array of 4-byte integers. 

The seek-key identifies the beginning of the returned data, as it does for 
STREAM _$GET_ REC. Use it in STREAM_$SEEK calls followed by 
STREAM_$GET_REC (not STREAM_$GET_PRIOR_REC) calls. 

If the returned status is nonzero, the seek-key is not useful. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 



USAGE 

STREAM_$GET_PRIOR_REC reads the previous record from the object. The object 
must be open on the specified stream. 

This call operates on file types UASC, PAD, HDR_UNDEF, and REC with record format 
F2. It will not work on REC files with record format VI, or on nonfile-type streams such 
as SIO lines, input pads, or mailboxes. STREAM _$ GET _ PRIOR _ REC works as 
follows: 

UASC and REC files 

If the seek-key is positioned at the beginning of a record, it is positioned 
to the previous record. If the seek-key is in the middle of a record, then 
its position is not changed. 

HDR_UNDEF files 

The seek-key is repositioned by subtracting the caller's buffer size from 
the current position. 

After these respective actions are taken, an ordinary STREAM _$GET_ REC operation is 
done. 

FORTRAN programs using this procedure in locate mode should use the pointer variable 
FORTRAN extension. Otherwise, call STREAM _$REDEFINE to set move mode before 
using this procedure. 

An error occurs if the stream manager cannot find a record at the current stream position - 
- for example, if the current position is beyond EOF or at BOF (beginning of file). 
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STREAM_$GET_REC 

Reads the next sequential record from an object. 

FORMAT 

STREAM_$GET_REC (stream-id. bufptr, buflen, retptr. retlen. seek-key, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

bufptr 

Pointer to the buffer into which the record may be read, in UNIV_PTR format. This is a 
4-byte integer. 

To obtain a value for bufptr, FORTRAN programs can use the IADDR function. Pascal 
programs can use the ADDR function. The buffer can be aligned on a byte boundary; 
therefore, the value of bufptr can be odd. 

buflen 

Number of bytes of data to be read. This is a 4-byte integer. 

If the number of bytes remaining in the record is less than buflen, STREAM_$GET_REC 
returns the remainder of the record. If the number of bytes remaining in the record is 
greater than buflen, the stream manager reads enough data to fill the buffer and returns a 
negative value in retlen. The absolute value of retlen is the number of bytes remaining in 
the record. 

OUTPUT PARAMETERS 

retptr 

Pointer to the data returned, in UNIV_PTR format. This is a 4-byte integer. 

Address the returned data only by using retptr. The stream manager may use "locate 
mode," in which it doesn't copy the desired data to the location indicated by bufptr. 
FORTRAN programs that call the stream manager in locate mode should use the "pointer 
variable" FORTRAN extension. 

Records are aligned on word boundaries. Therefore, if the procedure reads an entire record, 
the value of retptr will be word-aligned and positive. The value of retptr is meaningful 
only until execution of the next stream call for this stream. 

retlen 

Number of bytes of data returned. This is a 4-byte integer. 

If the number of bytes remaining in the record is less than buflen, 

STREAM _$GET_ PRIOR _REC returns the remainder of the record. The value of retlen 

is the number of bytes actually read. 

If the number of bytes remaining in the record is greater than buflen, the stream manager 
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reads enough data to fill the buffer and returns a negative value in retlen. The absolute 
value of the returned retlen is the number of unread bytes remaining in the record. 

seek- key 

Unique key identifying the location of the data read, in STREAM _$SK_T format. This 
is a three-element array of 4-byte integers. 

To obtain a seek-key value for the current stream position, call STREAM_$GET_REC 
with a buflen of 0. 

Use the seek-key value in STREAM_$SEEK calls followed by STREAM _$GET_ REC 
calls. 

If the returned status is nonzero, the seek-key is not useful. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM _$GET_REC returns at most the requested number of bytes of the next 
sequential record in the object. 

FORTRAN programs using this procedure in locate mode should use the pointer variable 
FORTRAN extension. Otherwise, call STREAM _$REDEFINE to set move mode before 
using this procedure. 

An error occurs if the stream manager cannot find a record at the current stream position — 
for example, if the current position is at EOF. 
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STREAM_$INQUIRE 

Returns information about an object. 



FORMAT 

STREAM_$ INQUIRE (input-mask, inquiry- type, attributes, error-mask, status) 

INPUT PARAMETERS 

input- mask 

Integer bit mask indicating the attributes for which information is requested, in 
STREAM_$INQUIRE_MASK_T format. This is a 4-byte integer. 

The following lists the predefined symbols for each bit position in the mask. 



Stream-id 

Object name 

Object name length 

Record length 

Temporary or permanent * 

Explicit record type 

ASCII or binary file 

Explicit move mode * 

Carriage control 

Record type 

Object concurrency (not implemented) 

Concurrency at open * 

Access type * 

Pre-existing object 

Header length 

File length 

Seek key * 

Current record length * 

Current relative record number * 

Number of blocks used 

Date and time last used 

Date and time last modified 

Sparsely written file * 

Object type 

Close stream on UNIX Exec call 

Forced STREAM_$GET_CONDITIONAL 

File in append mode 

Force locate mode 



* Attributes to which a stream must be open for information to be returned. 



Pascal and C programs specify these predefined values as members of a set. FORTRAN 
programs must add the desired values to each other to result in a correct input-mask value. 



Bit 





STREAM_$STRID 


Bit 


1 


STREAM_$0B J_NAME 


Bit 


1 


STREAM_$0B J_NAMLEN 


Bit 


2 


STREAM_$REC_LGTH 


Bit 


3 


STREAM_$TEMPORARY 


Bit 


4 


STREAM_$EXPLICIT_TYPE 


Bit 


5 


STREAM_$AB_FLAG 


Bit 


6 


STREAM_$EXPL I C I T_ML 


Bit 


7 


STREAM_$CC 


Bit 


8 


STREAM_$REC_TYPE 


Bit 


9 


STREAM_$CONC 


Bit 


10 


STREAM_$0C0NC 


Bit 


11 


STREAM_$0P0S 


Bit 


12 


STREAM_$PRE_EXIST 


Bit 


13 


STREAM_$HDR_LGTH 


Bit 


14 


STREAM_$F ILE_LENGTH 


Bit 


15 


STREAM_$SEEK_KEY 


Bit 


16 


STREAM_$CUR_REC_LEN 


Bit 


17 


STREAM_$CUR_REL_REC_NO 


Bit 


18 


STREAM_$BLKS_USED 


Bit 


19 


STREAM_$DTU 


Bit 


20 


STREAM_$DTM 


Bit 


21 


STREAM_$SPARSE 


Bit 


22 


STREAM_$OTYPE 


Bit 


23 


STREAM_$CLOSE_ON_EXEC 


Bit 


24 


STREAM_$NDELAY 


Bit 


25 


STREAM_$APPEND_MODE 


Bit 


26 


STREAM $F0RCED LOCATE 



N 



STREAM 



STREAM- 34 



o 



o 



STREAM_$INQUIRE 



inquiry- type 

Type of inquiry, in STREAM _$IR_ OPT format. Possible values are: 

STREAM_ $USE _ STRID 

Specifies an inquiry by stream ID. On input, the attribute record must 
contain the stream-id to which the request applies. On output, the 
attribute record contains the requested information, if the stream is open. 
If the stream is not open, an error is returned. 

STREAM _ $NAME _ CONDITIONAL 

Specifies an inquiry by name to be executed only if a stream is open to 
the object. On input, the attribute record must contain the object's 
pathname and name-length. On output, the attribute record contains the 
requested information if a stream is open. If no stream is open to the 
object, an error is returned. 

STREAM_ $NAME _ UNCONDITIONAL 

Specifies an unconditional inquiry by name. On input, the attribute 
record must contain the object's pathname and name-length. On output, 
the attribute record contains the requested information whether or not a 
stream is open. 

INPUT/OUTPUT PARAMETERS 

attributes 

Record containing attribute information, in STREAM _$IR_REC_T format. On input, 
this record contains a pathname or stream-id that identifies the object. On output, this 
record contains the returned information. 

For serial lines, STREAM _$ INQUIRE returns the default values. 

The attribute parameter is able to convey a large amount of information by passing it in 
many fields of one record (including a number of bit fields). These record fields are listed 
below along with their size and a brief explanation of the information they transmit. 

Stream-id STREAM_$ID_T. A 2-byte integer. Specified on input in conjunction 

with the STREAM _$USE_ STRID inquiry- type. 

Name-length a 2-byte integer. Name-length of the object. Specified on input in 

conjunction with the STREAM _$NAME_ CONDITIONAL and 
STREAM_$NAME_UNCONDITIONAL inquiry-type. 

Record length A longword. If the object has variable-length records, the length of the 
first record is returned; if fixed-length records, the fixed record length is 
returned. 
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Flagl 



A field of 16 bits containing Boolean and enumerated values. Each 
Boolean value occupies one bit in the flag. Enumerated types may 
occupy more than one bit depending on the number of possible values. 
The following table lists the bit number(s), the corresponding attribute, 
the data type of the attribute, and a brief explanation of possible values. 



Bit Number 


Attribute 


Data Type 


Explanation 


Bit 


Temporary 


Boolean 


TRUE if the object is temporary. 


Bit 1 


Explicit type 


Boolean 


TRUE if record type is explicit. 


Bit 2 


ASCII/Binary 


Boolean 


TRUE if data is ASCII, otherwise 
it is binary 


Bit 3 


Force move 
mode 


Boolean 


TRUE if move mode is used 
(only applies to open streams) . 


Bits 4.5 


Unused 1 






Bit 6 


Carriage 
control 


STREAM_$CC_T 


Either STREAM_$F77_CC (FORTRAN) 
or STREAM_$APOLLO_CC (DOMAIN) . 


Bits 7-9 


Unused 2 






Bits 10.11 


Record Type 


STREAM_$RTYPE_T 


Either STREAM_$F2 (fixed length) . 
STREAM_$V1 (variable-length) . or 
STREAM_$UNDEF (undefined) . 


Bits 12.13 


Unused 3 






Bits 14.15 


Object 
Concurrency 


STREAM_$FCONC_T 


Not implemented. Always is 
STREAM_$N_AND_N . 
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STREAM_$INQUIRE 

A word. This is a field of bits containing Boolean and enumerated values. 
Each Boolean value occupies one bit in the flag. Enumerated types may 
occupy more than one bit depending on the number of possible values. 
The following table lists the bit number(s), the corresponding attribute, 
the data type of the attribute, and a brief explanation of possible values. 



Bit Number 


Attribute 


Data Type 


Explanation 


Bits 16.17 


Unused 4 






Bits 18.19 


Concurrency 
at open 


STREAM_0M0DE_T 


Either STREAM_$UNREGULATED . 
STREAM_$NO_CONC_WRITE. or 
STREAM_$CONTROLLED_SHARING . Only 
returned from opened streams. 


Bits 20.21 


Unused 5 






Bits 2-24 


Access Type 


STREAM_$0P0S_T 


Either STREAM_$READ . 
STREAM_$WRITE. STREAM_$UPDATE. 
STREAM_$APPEND . or 
STREAM_$OVERWRITE . Only returned 
from opened streams. 


Bit 25 


Pre-existing 


Boolean 


TRUE if object already exists. 


Bits 26-31 


Unused 5 







Unused 6 
Header length 
File length 
Seek key 



A 2-byte integer. Length of streams header. 

A 4- byte integer. Total file length, in bytes (including header). 

STREAM_$SK_T. A three-element INTEGER*4 array. Current stream 
position. This attribute is only returned from opened streams. 



Current record length 

A 4-byte integer. Size of current record. This attribute is only returned 
from opened streams. 

Current relative record number 

A 4-byte integer. Only applies to files with fixed-length records. This 
attribute is only returned from opened streams. 

Blocks used A 4-byte integer. Number of disk blocks currently used for the file. Only 

applies to pads and disk files. 

Date/Time Used TIME_$CLOCKH_T. A 4-byte integer. Date and time of last use. 
Only applies to pads and disk files. 
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Date/Time Modified 

TME_$CLOCKH_T. A 4-byte integer. Date and time of last 
modification. Only applies to pads and disk files. 



Object type UID_$T. A two element INTEGER*4 array. Type UID of the object. 

The following table lists valid UID types. 



UASC_$UID 

RECORDS_$UID 

HDR_$UNDEF_$UID 

OB JECT_F ILE_$UID 

PAD_$UID 

INPUT_PAD_$UID 

SIO_$UID 

MBX_$UID 

MT $UID 



UASC file 

Record-structured file 

Nonrecord-structured file 

Object module file 

Saved transcript pad 

Input pad 

Serial line descriptor file 

Mailbox object 

Magnetic tape descriptor file 



Sparse flag 



Boolean. When TRUE, file allocation may have "holes." 



STREAM 
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Flag3 



A word. This is a field of bits containing Boolean and enumerated values. 
Each Boolean value occupies one bit in the flag. Enumerated types may 
occupy more than one bit depending on the number of possible values. 
The following table lists the bit number(s), the corresponding attribute, 
the data type of the attribute, and a brief explanation of possible values. 



O 



Bit Number 


Attribute 


Data Type 


Explanation 


Bits 16-27 


Unused 7 






Bit 29 


Close on exec 


Boolean 


TRUE causes stream to be closed 
upon an AUX exec call. 


Bit 30 


No delay mode 


Boolean 


When TRUE, any system call that 
reads data from a stream will 
act like STREAM_$GET_CONDITIONAL 
(returns if data not available) . 


Bit 31 


Append mode 


Boolean 


When TRUE, any call to 
STREAM_$PUT_REC or 
STREAM_$PUT_CHR does a seek to 
EOF before writing any data. 


Bit 28 


Force locate 


Boolean 


Normally, if the force move mode 




mode 




bit (bit 6) is not set, streams 
may use either move mode or 
locate mode. If this bit is set, 
streams will only use locate 
mode, the caller need not supply 
a buffer. This option can only 
be set for file-type streams 
(UASC, REC, HDR_UNDEF, and 
CASE HM) . 



Unused 8 



A 4-byte integer. 



O 



Name NAME_$PNAME_T. A character array of up to 256 elements. The 

name of the object. Specified on input with 
STREAM _ $NAME _ CONDITIONAL and 
STREAM_$NAME_UNCONDITIONAL inquiry-types. 

The array specified as the attribute parameter need not be large enough for every field, but 
just sufficient to span the required fields. For example, to inquire on explicit move mode, 
only a six-element INTEGER*2 array is required (for a FORTRAN program), because the 
necessary flag is in FLAGl. 

Accessing attribute record bit fields is discussed in detail in the Programming With General 
System Calls. 



OUTPUT PARAMETERS 



o 



error- mask 

Integer bit-mask indicating the requested fields that could not be returned, in 
STREAM_$INQUIRE_MASK_T format. This is a 4-byte integer. 
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This procedure may complete with partial success if it can return some, but not all, of the 
requested attributes. If an attribute is unavailable, STREAM _$INQUIRE sets the 
corresponding bit in the error mask and continues to inquire about other attributes. In 
cases of partial success, the returned status code is nonzero. The program must check the 
error mask to find out where the error occurred. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM _$INQUERE returns the attributes of the object specified in the mask. To 
receive the information you must specify either the stream ID of the object or the object 
name and name-length. However, some attributes such as access type apply only to objects 
to which a stream is open. These parameters are marked with asterisks in the inquiry mask 
parameter description above. 

The stream position does not change as a result of this call. 
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STREAM_$OPEN 

STREAM_$OPEN 

Opens a stream to an existing object. 

FORMAT 

STREAM_$OPEN (pathname, name-length, access, concurrency, stream-id. status) 

INPUT PARAMETERS 

pathname 

Name of the object to be opened, in NAME_$PNAME__T format. This is a character 
array of up to 256 elements. 

name- length 

Length of the pathname. This is a 2-byte integer. 

access 

Type of access requested, in STREAM _$OPOS_T format. Possible values are: 

STREAM_ $APPEND 

Permits adding data to the end of an object. The stream pointer points 
to the end of the object (EOF). 

STREAM_$MAKE_BACKUP 

Not for use with STREAM_$OPEN. (See below for a detailed 
description.) 

STREAM_ $OVERWRITE 

Permits replacing the entire contents of an object. The stream pointer is 
positioned at the start of the object data and data is truncated. 

STREAM _$READ 

Permits reading data from an existing object. 

STREAM_ $UPDATE 

Permits replacing selected portions of the contents of an object. The 
stream pointer is positioned at the start of the object data, just past the 
header if it has one. 

STREAM_$WRITE 

Same as STREAM_$UPDATE. 

concurrency 

Requested concurrency at open, in STREAM _$OMODE_T format. Possible values are: 

STREAM _ $CONTROLLED _ SHARING 

Does not allow concurrent read and write access. 

STREAM_ $N0 _ CONC _ WRITE 

Does not allow concurrent read and write access. 

STREAM_ $UNREGULATED 

Allows concurrent read and write access. 
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OUTPUT PARAMETERS 

stream- id 

Number of the stream on which the object was opened, in STREAM_$ID_T format. This 
is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This is a 4- byte integer. 

USAGE 

This routine opens a stream to the named object and assigns access and concurrency types. 
It returns the stream ID to be used in subsequent stream activity with the object. 

An error occurs if the object does not exist. 

STREAM_$OPEN does not return information about the object's characteristics. Use 

STREAM _$INQUIRE to obtain that information. C 

If the object already exists, its attributes remain the same when it is opened. For streams to 
SIO lines, however, "cooked" input mode is always in effect when the stream is opened. To 
change the object's attributes, call STREAM _$REDEFINE (or SIO_$CONTROL) before 
writing to the object. 
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STREAM_$PUT_CHR 

STREAM_ $PUT_ CHR 

Writes data to an object without terminating the current record, if one exists. 

FORMAT 

STREAM_$PUT_CHR (stream-id, bufptr. buflen, seek-key status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which an object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

bufptr 

Pointer to the data to be written, in UNIV_PTR format. This is a 4-byte integer. 

FORTRAN programs can use IADDR to obtain the buffer address for the bufptr parameter. 
Pascal programs can use ADDR. Alternately, programs in either language can use pointer 
variables. 

buflen 

Number of bytes of data to be written. This is a 4-byte integer. 

OUTPUT PARAMETERS 

seek-key 

Unique key identifying the location of the data written, in STREAM_$SK_T format. 
This is a three-element array of 4-byte integers. 

The seek key allows random access to the output data by a subsequent STREAM_$SEEK 
call. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM_$PUT_CHR writes the specified number of bytes to the object, but does not 
terminate a record. 

Use this procedure to write data in nonrecord-structured files or to compose records piece 
by piece. Be sure to call STREAM_$REDEFINE to set STREAM_$UNDEF as the record 
type, and HDR_UNDEF_$UID as the object type, before writing any output. 

Records of fixed-length format automatically change to variable-length if this write 
operation extends the current record beyond the length of existing records. In this case, no 
error occurs. For files with explicit fixed-length records, an error occurs if this write 
operation extends the current record beyond the fixed-record size. 

For files with variable-length records, no record length checking is performed. Tin i< fore, 
take care not to alter the count field of the following record. 
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Record size can increase as a result of this call, but cannot decrease. For instance, after you 
overwrite the first 20 bytes of a 32-byte record, the last 12 bytes still contain the original 
data, and the count field remains the same. To terminate a record and update its count 
field, .use STREAM _$PUT_REC. 

STREAM_$PUT_CHR and STREAM_$PUT_REC operate identically when applied to 
SIO lines, UASC files, and keyboards. 
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STREAM_$PUT_REC 

Writes data to an object and terminates the current record, if one exists. 

FORMAT 

STREAM_$PUT_REC (stream-id, bufptr. buflen, seek-key. status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

bufptr 

Pointer to the data to be written, in UNIV_PTR format. This is a 4-byte integer. 

FORTRAN programs can use IADDR to obtain the buffer address for the bufptr parameter. 
Pascal programs can use ADDR. Alternately, programs in either language can use pointer 
variables. 

buflen 

Number of bytes of data to be written. This is a 4-byte integer. 

For files with explicit fixed-length records, an error occurs if the total record length is not 
equal to the fixed-record length. 

If you specify a buflen of zero, STREAM_$PUT_REC simply terminates the current 
record and updates its count field. 

OUTPUT PARAMETERS 

seek-key 

Unique key identifying the location of the data in the object, in STREAM _$SK_T 
format. This is a three-element array of 4-byte integers. 

The seek key allows random access to the output data by a subsequent STREAM_$SEEK 
call. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM _$PUT_REC queues data for output to the object. It does not necessarily write 
the data on the device. Device writes may be performed asynchronously. 

Records of default format (implicit fixed-length) automatically change to variable-length if 
the new record differs in length from any existing records. No error occurs. 

Existing data in variable-length records are overwritten if the stream position is not at 
EOF. No error occurs. 
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STREAM _$PUT_REC never inserts newline characters in the object on its own. You 
must do this yourself if you want newlines to appear in the object. 

STREAM_$PUT_CHR and STREAM _$PUT_ REC operate identically when applied to 
SIO lines, UASC files, and keyboards. 
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STREAM _ $REDEFINE 

Changes one or more attributes of an object that is open on a stream. 



FORMAT 

STREAM_$REDEFINE (stream-id, input-mask, attributes, error-mask, status) 



o 



INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM _$ID_T format. This is a 
2-byte integer. 

input-mask 

An integer bit mask showing which attributes you want to redefine, in 
STREAM_$REDEF_MASK_T format. This is a 4-byte integer. 

Bits 4 through 9 are the ones most commonly changed. The following lists the predefined 
symbols for each bit position in the mask. 
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Bit 


1 


STREAM $0BJ NAME 


Bit 


1 


STREAM $0BJ NAMLEN 


Bit 


2 


STREAM $REC LGTH 


Bit 


3 


STREAM $TEMPORARY . 


Bit 


4 


STREAM $EXPLICIT TYPE 


Bit 


5 


STREAM $AB FLAG 


Bit 


6 


STREAM $EXPLICIT ML 


Bit 


7 


STREAM $CC 


Bit 


8 


STREAM $REC TYPE 


Bit 


9 


STREAM $C0NC 


Bit 


10 


STREAM $0C0NC 


Bit 


11 


STREAM $0P0S 



Bit 21 STREAM_$SPARSE 

Bit 22 STREAM_$OTYPE 

Bit 23 STREAM_$CLOSE_ON_EXEC 

Bit 24 STREAM_$NDELAY 

Bit 25 STREAM_$APPEND_MODE 

Bit 26 STREAM $F0RCED LOCATE 



Object name 

Object name length 

Record length 

Temporary or permanent 

Explicit record type 

ASCII or binary file 

Explicit move mode 

Carriage control 

Record type 

Object concurrency (not implemented) 

Concurrency at open 

Access type 

Sparsely written file 

Object type 

Close stream on DOMAIN/IX Exec call 

Forced STREAM_$GET_CONDITIONAL 

File in append mode 

Force locate mode 



O 



Pascal and C programs specify these predefined values as members of a set. FORTRAN 
programs must add the desired values to each other to result in a correct input-mask value. 

Note that some bit numbers are missing (0, 12 - 20). This is because 

STREAM _$INQUIRE and STREAM _$REDEFINE use the same attribute record, 

however certain attributes that can be inquired upon cannot be redefined. 

attributes 

Record containing new values for attributes, in STREAM_$IR_REC_T format. 

The attribute parameter is able to specify redefinition of a large number of attributes by 
passing information in many fields of one record (including a number of bit fields). These 
record fields are listed below along with their size and a brief explanation of the information 
they transmit. 
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Stream-id STREAM _$ID_T. A 2-byte integer. Not redefinable. 

Name-length a 2-byte integer. Name-length of the object. Specified on input in 

conjunction with the STREAM_$NAME_ CONDITIONAL and 
STREAM_$NAME_UNCONDITIONAL inquiry-type. 

Record length A longword. If the object has variable-length records, the length of the 
longest record is returned; if fixed-length records, the fixed record length 
is returned. 

Flagl A field of 16 bits containing Boolean and enumerated values. Each 

Boolean value occupies one bit in the flag. Enumerated types may 
occupy more than one bit depending on the number of possible values. 
The following table lists the bit number(s), the corresponding attribute, 
the data type of the attribute, and a brief explanation of possible values. 



Bit Number 


Attribute 


Data Type 


Explanation 


Bit 


Temporary 


Boolean 


TRUE if the object is temporary. 


Bit 1 


Explicit type 


Boolean 


TRUE if record type is explicit. 


Bit 2 


ASCII/Binary 


Boolean 


TRUE if data is ASCII, otherwise 
it is binary. 


Bit 3 


Force move 
mode 


Boolean 


TRUE if move mode is used, 
(only applies to open streams) 


Bits 4.5 


Unused 1 






Bit 6 


Carriage 
control 


STREAM_$CC_T 


Either STREAM_$F77_CC (FORTRAN) 
or STREAM_$APOLLO_CC (DOMAIN) . 


Bits 7-9 


Unused 2 






Bits 10,11 


Record Type 


STREAM_$RTYPE_T 


Either STREAM_$F2 (fixed length) , 
STREAM_$V1 (variable-length) , or 
STREAM_$UNDEF (undefined) . 


Bits 12,13 


Unused 3 






Bits 14,15 


Object 
Concurrency 


STREAM_$FCONC_T 


Not implemented. Always 
STREAM_$N_AND_N . 



Flag2 



A word. This is a field of bits containing Boolean and enumerated values. 
Each Boolean value occupies one bit in the flag. Enumerated types may 
occupy more than one bit depending on the number of possible values. 
The following table lists the bit number(s), the corresponding attribute, 
the data type of the attribute, and a brief explanation of possible values. 
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Bit Number 


Attribute 


Data type 


Explanation 


Bits 16,17 


Unused 4 






Bits 18.19 


Concurrency 
at open 


STREAM_0M0DE_T 


Either STREAM_$UNREGULATED . 
STREAM_$NO_CONC_WRITE. or 
STREAM_$CONTROLLED_SHARING . Only 
returned from opened streams. 


Bits 20.21 


Unused 5 






Bits 2 -24 


Access Type 


STREAM_$0P0S_T 


Either STREAM_$READ , 
STREAM_$WRITE, STREAM_$UPDATE. 
STREAM_$APPEND . or 
STREAM_$OVERWRITE. Only returned 
from opened streams. 


Bit 25 


Pre-existing 


Boolean 


Not redefinable. 


Bits 26-31 


Unused 5 







Unused 6 
Header length 
File length 
Seek key 



A 2-byte integer. Not redefinable. 

A 4-byte integer. Not redefinable. 

STREAM_$SK_T. A three-element INTEGER*4 array. Not 
redefinable. 



Current record length 

A 4-byte integer. Not redefinable. 

Current relative record number 

A 4-byte integer. Not redefinable. 

Blocks used A 4-byte integer. Not redefinable. 

Date/Time Used TIME_$CLOCKH_T. A 4-byte integer. Not redefinable. 

Date/Time Modified 

TIME_$CLOCKH_T. A 4-byte integer. Not redefinable. 

.Object type UID_$T. A two element INTEGER*4 array. Type UID of the object. 

The following table lists valid UID types. 

UASC_$UID UASC file 

RECORDS_$UID Record-structured file 

HDR_$UNDEF_$UID Nonrecord-structured file 

OBJECT_FILE_$UID Object module file 

PAD_$UID Saved transcript pad 

INPUT_PAD_$UID Input pad 

SI0_$UID Serial line descriptor file 

MBX_$UID Mailbox object 

MT_$UID Magnetic tape descriptor file 



STREAM-49 



STREAM 



STREAM $REDEFINE 



Sparse flag Boolean. When TRUE, file allocation may have "holes", 

Programming With General System Calls manual. 



See the 



Flag3 



A word. This is a field of bits containing Boolean and enumerated values. 
Each Boolean value occupies one bit in the flag. Enumerated types may 
occupy more than one bit depending on the number of possible values. 
The following table lists the bit number(s), the corresponding attribute, 
the data type of the attribute, and a brief explanation of possible values. 



Bit Number 


Attribute 


Data Type 


Explanation 


Bits 16-27 


Unused 7 






Bit 29 


Close on exec 


Boolean 


TRUE causes stream to be closed 
upon an DOMAIN/IX exec call. 


Bit 30 


No delay mode 


Boolean 


When TRUE, any system call that 
reads data from a stream will 
act like STREAM_$GET_CONDITIONAL 
(returns if data not available) . 


Bit 31 


Append mode 


Boolean 


When TRUE, any call to 
STREAM_$PUT_REC or 
STREAM $PUT CHR does a seek to 
EOF before writing any data. 


Bit 28 


Force locate 


Boolean 


Normally, if the force move mode 




mode 




bit (bit 6) is not set, streams 
may use either move mode or 
locate mode. If this bit is set, 
streams will only use locate 
mode; the caller need not supply 
a buffer. This option can only 
be set for file-type streams 
(UASC, REC, HDRJJNDEF, and 
CASE_HM) . 



Unused 8 A 4-byte integer. 

Name NAME_$PNAME_T. A character array of up to 256 elements. The 

name of the object. Specified on input with 
STREAM_$NAME_CONDITIONAL and 
STREAM_$NAME_UNCONDITIONAL inquiry types. 

The array specified as the attribute parameter need not be large enough for every field, but 
just sufficient to span the required fields. For example, to redefine explicit move mode, 
only a six-element INTEGER*2 array is required (for a FORTRAN program), because the 
necessary flag is in FLAGl. 

Accessing attribute record bit fields is discussed in detail in the Programming With General 
System Calls handbook. 
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STREAM_ $REDEFINE 

OUTPUT PARAMETERS 

error- mask 

An integer bit-mask indicating any requested changes that were not made, in 
STREAM_$REDEF_MASK_T format. This is a 4-byte integer. 

This procedure may complete with partial success if it can redefine some, but not all, of the 
requested attributes. If an attribute is not changed, STREAM _$REDEFINE sets the 
corresponding bit in the error mask and continues to redefine other attributes. In cases of 
partial success, the returned status code is nonzero. The program must check the error 
mask to find out where the error occurred. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM _$REDEFINE changes one or more attributes of an object to which you have a 
stream open. Wherever bits are set in the input mask, STREAM _$REDEFINE tries to 
copy information from the corresponding fields of the attribute record to the object. 
Wherever bits are not set in the input mask, the corresponding attributes of the object do 
not change. 

FORTRAN programs that use the stream manager to read files must call 
STREAM _ $REDEFINE to request explicit move mode. 

You can use STREAM _$REDEFINE only on streams with write access. However, you can 
use it to change read access to write access. 

You cannot use STREAM _$REDEFINE to change the stream position (use 
STREAM_$SEEK instead), to change the object's length (use STREAM _$TRUNCATE 
instead), or to change a serial line's attributes (use SIO_$CONTROL). 
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STREAM_ $REPLACE 

STREAM_ $REPLACE 

Writes data to an object without changing the length of the current record. 

FORMAT 

STREAM_$REPLACE (stream-id, bufptr, buflen, seek-key, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

bufptr 

Pointer to the data to be written, in UNIV_PTR format. This is a 4-byte integer. 

FORTRAN programs can use IADDR to obtain the buffer address for the bufptr parameter. 
Pascal programs can use ADDR. Alternately, programs in either language can use pointer 
variables. 

buflen 

Number of bytes of data to be written. This is a 4-byte integer. 

OUTPUT PARAMETERS 

seek- key 

Unique key identifying the location of the output data in the object, in STREAM_$SK_T 
format. This is a three-element array of 4-byte integers. 

The seek key allows random access to the output data by a subsequent STREAM_$SEEK 
call. 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM _$REPLACE replaces a record in the object. Call STREAM _$PUT_REC to 
add records to an object. 

For record-structured objects, this call terminates the current record. The length of the 
current record must be exactly the same as the length of the record it replaces. An error 
occurs if the record lengths are different. You can use STREAM _$PUT_REC and 
STREAM_$PUT_CHR to overwrite existing data in a file or pad with no record length 
checking. 
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STREAM_ $REPLACE 

For nonrecord-structured objects, this call writes the specified number of characters. No 
record-length errors can occur. 

Like STREAM_$PUT_REC, STREAM _$REPLACE queues data for output to the 
object. It does not necessarily write the data on the device. Device writes may be 
performed asynchronously. 
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STREAM_$SEEK 

STREAM_$SEEK 

Moves the stream position. 

FORMAT 

STREAM_$SEEK (stream-id. seek-base, seek- type, 
{seek-key I signed-off set}, status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

seek- base 

Type of data on which the seek is based, in STREAM _$PARM1_T format. Possible 
values are: 

STREAM_$CHR 

Character-based seek. 

STREAM_$EOF 

End-of-file based seek. (Any offset specified with STREAM_$EOF is 
ignored.) 

STREAM_$KEY 

Keyed value-based seek. 

STREAM_$REC 

Record-based seek. 

seek- type 

Value defining the relationship between the seek-base and the seek-key or signed-offset, in 
STREAM _$PARM2_T format. Possible values are: 

STREAM_ $RELATIVE 

Moves the stream position relative to the current stream marker. 
Relative positioning is only valid for character (STREAM_$CHR) and 
record (STREAM_$REC) based seeks. Specifying either 
STREAM_$EOF or STREAM _$KEY with STREAM _$RELATIVE 
results in an error status. A positive offset moves the stream position 
towards EOF and a negative offset moves the stream position towards 
the beginning of the object. Relative seeks start at 0; that is, an offset of 
denotes the current position. 

STREAM_ $ABSOLUTE 

Seeks for an absolute position in the object. In absolute seeks, all four 
seek bases are valid. STREAM_$EOF and STREAM_$KEY can only 
be used in absolute seeks. Absolute character and record-based seeks 
start from the beginning of the object (past the header) if the offset is 
positive. If the offset is negative, the seek starts at EOF. Absolute seeks 
start at 1. An error occurs if you specify an offset of for an absolute 
seek. 
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seek- key 

Unique value identifying the data sought, in STREAM_$SK_T format. This is a 
three-element array of 4-byte integers. 

signed- offset 

Offset to be used in calculating the new stream position. This is a 4-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM_$SEEK moves the stream marker to a specific location, or to an offset from a 
known location. It does not move any data. 

An error occurs if the object does not support random access. 

An error occurs if the program attempts to move the stream position beyond the beginning 
or end of the file. 

Character-based seeks in record-structured objects cannot move the stream position beyond 
the current record. 

Record-based seeks apply only to objects with fixed-length records. For objects with 
variable-length records, save the seek keys returned when the object is written, then 
perform keyed seeks. 

For UASC files, specifying STREAM_$REC simulates a fixed-length record seek by finding 
the length of the first record in the file and using that as the record length for all records. 
STREAM _$CHR-seeks work like they do in nonrecord-structured files. 

The stream marker must be aligned on a record boundary when you specify 
STREAM_$REC. If alignment is incorrect, an error occurs. Similarly, if positioning is 
relative to EOF (that is, a negative offset), the current EOF must be on a record boundary. 

The following examples illustrate the difference between absolute and relative seeks. The 
first example is an absolute seek for the 16th character in the object: 

STREAM_$SEEK(stream_id, STREAM_$CHR, STREAM_$ABSOLUTE. 
16, status) 

The second example positions the stream marker seven records closer to the beginning of 
the object than it was before the call. 

STREAM_$SEEK(stream_id, STREAM_$REC. STREAM_$RELATIVE, 
-7, status) 
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STREAM_ $TRUNCATE 

Writes EOF at the current stream position. 

FORMAT 

STREAM_$TRUNCATE (stream-id. status) 

INPUT PARAMETERS 

stream- id 

Number of a stream on which the object is open, in STREAM_$ID_T format. This is a 
2-byte integer. 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This is a 4-byte integer. 

USAGE 

STREAM _$TRUNCATE decreases the value of the file length attribute to match the 
stream pointer's current position. (Writing data to a stream that lengthens the object 
implicitly increases this attribute's value.) This sets EOF to the stream pointer's position, 
effectively deleting any data in the object past the stream pointer. If the stream position is 
already at EOF, truncating the object has no effect. 

You can only truncate disk files and pads that the Display Manager is not using. Trying to 
truncate any other type of object returns an error status code. 

Truncating an object does not close the stream. 
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ERRORS 

STATUS _$OK 

Successful completion. 

STREAM_ $ALREADY_EXISTS 

STREAM _$WRITE specified on STREAM _$CREATE. 

STREAM _ $BAD _ CHAR _ SEEK 

Attempted character seek before start of current (variable length) record. 

STREAM_$BAD_COUNT_FIELD_IN_FILE 
Count field for current record is bad. 

STREAM_$BAD_FILE_HDR 

File header is no good ( CRC error ). 

STREAM_ $BAD _LOCATION 

Bad location parameter in create call. 

STREAM_ $BAD _ OPEN_xp 

OPEN_XP must reference a stream that is already open on this node. 

STREAM_$BAD_POS_ON_REC_SEEK 

Relative record seek is not legal unless the reference point is on record boundary. 

STREAM _ $BAD _RELATED _PAD 

PAD_$CREATE attempted with an invalid or unopened related pad. 

STREAM_ $BAD _ SHARED _ CURSOR_REFCNT 

Reference count on a shared file cursor went below zero. 

STREAM_ $BOF _ERR 

Attempted seek beyond BOF; e.g., offset=0. 

STREAM_ $CANT_DELETE _ OLD _ NAME 

WARNING : New name added but old cannot be deleted. 

STREAM_ $CANT _ SWITCH 

Too many mapped objects to perform switch. 

STREAM _ $CLOSE _ ANOMALY 

WARNING : Close successful but name of (temporary) object on this stream no longer 
references the same object. 

STREAM_ $CONCURRENCY_ VIOLATION 

Requested access violates concurrency constraints. 

STREAM_$DEVICE_MUST_BE_LOCAL 

Cannot open stream to remote device. 

STREAM_$DIR_NOT_FOUND 

Could not find directory in pathname on create. 

STREAM_$END_OF_FILE 
End of file. 

STREAM_$EOF_PAD_PUT_ERR 

. PUT_REC legal only at EOF on pads; EOF has moved. 
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STREAM_$FILE_TROUBLE_WARNING 

WARNING: (SALVAGER) File trouble bit set in VTOCE. 

STREAM_ $FROM_ STRID _NOT_ OPEN 

From stream is not open on switch request. 

STREAM_$ID_OOR 

Stream ID out-of-range (invalid). 

STREAM_ $ILL _FORCED _LOCATE 

Forced locate is only legal for disk files. 

STREAM_$ILLEGAL_NAME_REDEFINE 

Attempted name change requires copying file. 

STREAM_$LLLEGAL_OBJ_TYPE 

Cannot open a stream for this type of object. 

STREAM_ $ILLEGAL _ OPERATION 

This operation is illegal on named stream. 

STREAM _ $ILLEGAL _ PAD _ CLOSE 

Illegal to close transcript pad before related input pad. 

STREAM _ $ILLEGAL _ PAD _ CREATE _ TYPE 

PAD _ CREATE illegal with this type of object. 

STREAM _ $ILLEGAL _ PARAM _ COMB 

Illegal parameter combination for this operation. 

STREAM_$ILLEGAL_W_VAR_LGTH_RECS 

Operation illegal with variable length records. 

STREAM_$INQUIRE_TYPE_ERR 

Inquire (by name) about object that cannot be opened on a stream because of its type. 

STREAM_ $INQUIRE_ WARNING 

WARNING : Inquire-by-name is returning data only on first of multiple streams on 
which object is currently open. 

STREAM_ $INSUFF _MEMORY 

Not enough virtual memory. 

STREAM_ $INSUFFICIENT_RIGHTS 

Insufficient rights for requested access to object. 

STREAM_ $INTERNAL _FATAL _ERR 

Internal fatal error on table reverification. 

STREAM_ $INTERNAL _MM_ERR 

Internal fatal error in stream memory management (windowing). 

STREAM_ $INVALID _DATA 

Bad data in call to VT_$PUT. 

STREAM_$NAME_CONFUSION 

Object already open under another name on another stream. 

STREAM_$NAME_NOT_FOUND 
Name not found. 
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STREAM _ $NAME _ REQD 

STREAM _$OPEN without a name is illegal. 

STREAM_ $NEED _MOVE_MODE 

Forced locate is set and could not do it. 

STREAM _ $NEVER _ CLOSED 

System (or process) crash prevented complete close. 

STREAM _ $NO _ AVAIL _ TARGET 

No available target stream to switch to. 

STREAM_ $NO _MORE _ STREAMS 
No more streams. 

STREAM_ $NO _RIGHTS 

No rights to access object. 

STREAM_ $NO _ SUCH_ VERSION 

Specified DSEE version does not exist. 

STREAM_ $NO _ TABLE _ SPACE 

Table space error; cover stream table exhausted. 

STREAM _ $NOT _ OPEN 

Operation attempted on unopened stream. 

STREAM_$NOT_THRU_LINK 

Cannot create file though link. 

STREAM_$OBJ_DELETED 
File has been deleted. 

STREAM_$OBJECT_NOT_FOUND 

Object associated with this name not found (may not exist). 

STREAM _$OBJECT_READ_ ONLY 

Cannot open this object for writing. 

STREAM_ $OUT _ OF _ SHARED _ CURSORS 

Per-mode shared file cursor pool is exhausted. 

STREAM_$PART_REC_WARN 

WARNING : Partial record at the end of a file with fixed length records. 

STREAM_$PERM_FILE_NEEDS_NAME 

Only temporary files may be unnamed. 

STREAM_ $PUT_BAD _REC _LEN 

Attempted put of wrong length record. 

STREAM_ $READ _ ONLY_ERR 

Attempted write to read-only stream. 

STREAM_$REDEFINE_PAD_ERR 

Cannot redefine this attribute of a pad. 

STREAM_ $REPLACE_LGTH_ERR 

Attempted record length change on replace request. 
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STREAM_$RESOURCE_LOCK_ERR 

Unable to lock resources required to process request. 

STREAM_$SIO_NOT_LOCAL 
SIO object not in /DEV. 

STREAM _ $SOMETHING _FAILED 

Partial or complete failure of inquire or redefine (ERR_MASK is nonempty). 

STREAM _ $STREAM _ NOT _ FOUND 

No stream found in conditional inquire. 

STREAM_$XP_BUF_TOO_SMALL 

Buffer supplied to GET_XP too small. 
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TIME 



The TIME (Timer) programming calls manage the real-time interval clock. This section describes 
their data types, call syntax, and error codes. Refer to the Introduction at the beginning of this 
manual for a description of data- type diagrams and call syntax format. 
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TIME DATA TYPES 



CONSTANTS 

TIME_$ABSOLUTE 
TIME_$CLOCKH_KEY 
TIME $RELATIVE 



Specifies absolute time. 
Eventcount key value. 
Specifys relative time. 



DATA TYPES 

EC2_$PTR_T 
STATUS $T 



byte: 
offset 



31 



A 4-byte integer. Address of an eventcount. 

A status code. The diagram below illustrates the 
STATUS _$T data type: 



field name 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 • 

23). 
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TIME $CLOCK T 



code 

A signed number that identifies the type of error 

that occurred (bits - 15). 

Internal representation of time. The diagram below 
illustrates the TME_$CLOCK_T data type: 



predefined 
record 



byte: 
offset 



field name 



o 



time_$clockh_t 


0: 
4: 


integer 


high 




integer 




low 






Field Description: 






high 






High 32 bits of the clock. 






low 






Low 16 bits of the clock. 


predefined 
record 


byte: 
offset 

0: 
2: 




field name 




positive 
integer 




high 16 




positive integer 


low 32 



o 



Field Description: 

highl6 

High 16 bits of the clock. 

low32 

Low 32 bits of the clock. 



TIME $KEY T 



A 2-byte integer. An event count key. One of the 
following predefined values: 



TIME $REL ABS T 



TIME_$CLOCKH_KEY 
Only permissible value. 

A 2-byte integer. An indicator of type of time. 
One of the following predefined values: 



TIME_$RELATIVE 
Relative time. 



TIME_$ABSOLUTE 
Absolute time. 
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TIME_$CLOCK 

TIME_$CLOCK 

Returns the current UTC time. 

FORMAT 

TIME_$CLOCK (clock) 

OUTPUT PARAMETERS 

clock 

The current Coordinated Universal Time, in TIME_$CLOCK_T format. This data type 
is 6 bytes long. See the CAL Data Types section for more information. 

USAGE 

TIME_$CLOCK returns the current time of day, in UTC format. It is represented as the 
number of 4-microsecond periods that have elapsed since January 1, 1980 at 00:00. 

To get the local time, use CAL _ $GET_LO CAL _ TIME instead of this procedure. To 
compute the local time from the value returned by TIME_$CLOCK, use 
CAL $APPLY LOCAL OFFSET. 
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TIME_$GET_EC 

TIME_$GET_EC 

Gets the address of the time eventcount, which is advanced about every 0.25 second. 

FORMAT 

TIME_$GET_EC (time-key. eventcount-pointer, status) 

INPUT PARAMETERS 

time- key 

The key specifying which time eventcount the system should return, in TIME_$KEY_T 
format. This is a 2-byte integer. 

Currently the only allowable value is TIME _$CLOCKH_ KEY. 

OUTPUT PARAMETERS 

event count- p oint er 

The eventcount address to be obtained, in EC2_$PTR_T format. This is a 4-byte 
integer. 

EC2_$PTR_T is a pointer to an EC2_$EVENTCOUNT_T array. See the EC2 Data 
Types section for more information. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the 
TIME_$ Data Types section for more information. 

USAGE 

EC2_$PTR_T is a pointer to an EC2_$EVENTCOUNT_T array. See the EC2 Data 
Types section for a description of eventcount data structures. 

TIME_$GET_EC outputs an eventcount that gets advanced about every 1/4 second. 
Thus, it can be passed to EC2_$WAIT to wait for a specific interval of time to elapse. 

The interval between successive advances of the eventcount is nominally 262,144 
microseconds (about 0.25 second). The exact interval changes slightly with system load. 

For a ten-second wait, you might use: 

TIME_$GET_EC (....gets time_eventcount ....) 

EC2_$READ ( . . . . gets current_eventcount_value . . . . ) 

EC2_$WAIT (. . . . current_eventcount + 40. time_eventcount . . . .) 

See Eventcounts Chapter of the Programming With General System Calls manual for more 
information. 
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TIME_$WAIT ^~^ 

Suspends the calling process for a specified time. V_ ^ 

FORMAT 

TIME_$WAIT (rel-abs, clock, status) 

INPUT PARAMETERS 

rel-abs 

Type of clock value supplied, in TIME_$REL_ABS_T format. This is a 2-byte integer. 
Specify only one of the following predefined values: 

TIME _ $RELATIVE 

Clock specifies the number of 4-microsecond periods to wait before 
resuming process execution. 

P 

TIME_$ABSOLUTE V> 

Clock contains the UTC system time for which to wait before resuming 
process execution. 

clock 

The relative or absolute time for which to wait before resuming process execution, in 
TIME_$CLOCK_T format. This data type is 6 bytes long. See the CAL Data Types 
section for more information. 

Note that if you specify TIME _$ ABSOLUTE in the rel_abs parameter, TIME_$WAIT V 

expects a UTC time. (You can remove a local time offset with the 
CAL_$REMOVE_LOCAL_OFFSET call.) 

OUTPUT PARAMETERS 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the CAL / ^ _ ~^ 

Data Types section for more information. 



USAGE 



TIME_$WAIT suspends the calling process until a relative time elapses or an absolute 
time occurs. 

A nonzero status is returned if the operating system has insufficient internal table space to 
process the request. 
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ERRORS 

STATUS _$OK 

Successful completion. 

TIME _$BAD_ INT 

Bad timer interrupt. 

TIME_$BAD_KEY 

Bad key to TME_$GET_EC. 

TIME _ $NO _ Q _ENTRY 

Error from TIME _$ AD VANCE. 

TIME_$NOT_FOUND 

Entry to be canceled not found. 

TIME _ $ WAIT _ QUIT 

Wait interrupted by quit fault. 
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This section describes the call syntax for the TONE programming call. The TONE call does not 
use special data types or produce unique error messages. Refer to the Introduction at the 
beginning of this manual for a description of call syntax format. 
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TONE_$TIME 

TONE_$TIME 

Makes a tone. The tone remains on for the time indicated in the call. 

FORMAT 

TONE_$TIME (time) 

INPUT PARAMETERS 

time 

Length of the tone, in T1ME_$CL0CK_T format. This data type is a 48-bit integer 
value. 

USAGE 

Only DOMAIN nodes shipped after April 19, 1982 contain a working speaker. 
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TPAD _ $INQUIRE TPAD-5 

TPAD $SET MODE TPAD-8. 
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The TPAD (Touchpad) programming calls maintain the touchpad and mouse. This section 
describes their data types and call syntax. The TPAD calls do not produce unique error 
messages. Refer to the Introduction at the beginning of this manual for a description of 
data-type diagrams and call syntax format. 
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TPAD DATA TYPES 



DATA TYPES 



TPAD_$MODE_T A 2-byte integer. Cursor mode operations for the 

touchpad and mouse. They establish how 
movements of the" finger affect the cursor position 
on the display. Note the only meaningful mode for 
a mouse is TPAD_$RELATIVE. One of the 
following predefined values: 

TPAD_$ABSOLUTE 

Touchpad corresponds directly to the display. 
When a finger is placed on the touchpad, the 
cursor jumps to the corresponding position on 
the screen. 

TPAD_$RELATr/E 

Cursor movement is relative to the current 
position. It moves only when a finger moves 
across the pad, it does not move when a finger 
is placed on touchpad. 

TPAD_$REL_ABS 

Cursor moves when finger is placed on the 
touchpad and when a finger moves across the 
pad. It does not move if a finger is lifted and 
replaced quickly. 
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STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


ail 


0: 


1 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 



O 



fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 

mode 

The module that encountered the error (bits 16 

23). 



code 

A signed number that identifies the type of error 

that occurred (bits - 15). 
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TPAD _ $INQ _DTYPE 

TPAD_$INQ_DTYPE 

Returns the name of the last type of locating device used. 

FORMAT 

device = TPAD_$INQ_DTYPE 

INPUT PARAMETERS 

None. 

OUTPUT PARAMETERS 

None. 

RETURN VALUE 

device 

Value indicating the last locating device used to provoide input, in ^- ■ - y 

TPAD _$DEV_ TYPE _T format. This data type is two bytes long. Specify one of the 
following predefined values: 

TPAD_$UNKNOWN 
TPAD_$HAVE_TOUCHPAD 
TPAD_$HAVE_MOUSE 
TPAD_$HAVE_BITPAD 

USAGE 

If no locator input has been detected since the node was last booted, this call returns 
TPAD $UNKNOWN. 
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TPAD_$INQUIRE 

TPAD_$INQUIRE 

Returns information about the current touchpad mode. 

FORMAT 

TPAD_$INQUIRE (mode, x-scale, y-scale. hysteresis, origin) 

INPUT PARAMETERS 

None. 

OUTPUT PARAMETERS 

mode 

Cursor mode, in TPAD_$MODE_T format. This is a 2-byte integer. Specify one of the 
following predefined values: 

TPAD_$ABSOLUTE 
TPAD_$RELATIVE 
TPAD_$REL_ABS 

x-scale 

Scale factor in the x dimension. This is a 2-byte integer. 

y-scale 

Scale factor in the y dimension. This is a 2-byte integer. 

hysteresis 

Hysteresis factor, in pixels. This is a 2-byte integer. 

This hysteresis factor prevents the touchpad manager from responding to any minor 
movements you make unintentionally. This value defines a "box" around your finger. The 
touchpad manager does not move the cursor if your finger stays within this box. 

If your finger moves beyond the box, the touchpad manager subtracts the hysteresis value 
from the distance moved, and moves the cursor the remaining distance. The default factor 

is 5. 

origin 

The point of origin for x and y in SMD_$POS_T format. This data type is 4 bytes long. 

USAGE 

Use this call to save the touchpad mode for later restoration, or to change one aspect of the 
mode without changing any other aspects. For example, you can use the output from this 
call as the input to the TPAD_$SET_MODE call. 
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TPAD_$RE_RANGE 

TPAD_$RE_RANGE 

Re-establishes the touchpad raw data range. 

FORMAT 

TPAD_$RE_RANGE () 

INPUT PARAMETERS 

None. 

OUTPUT PARAMETERS 

None. 

USAGE 

This call re-establishes the touchpad raw data range over the next 1000 data points. This is ( 

also done for you at system boot. See the section on Touchpad Modes in Programming with v -- 

General System Calls for a description of the touch pad raw data range. 
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TPAD _ $SET_ CURSOR 

TPAD _ $SET _ CURSOR 

Re-establishes the touchpad origin in relative mode. The call to TPAD _$SET_ CURSOR 
can occur at any time and affects subsequent touchpad inputs. 

FORMAT 

TPAD_$SET_CURSOR (origin) 

INPUT PARAMETERS 

origin 

A screen position that will be the origin for subsequent data points from the touchpad in 
relative mode or in absolute/relative mode, in SMD_$POS_T format. This data type is 4 
bytes long. 

OUTPUT PARAMETERS 

None. 



USAGE 

The system remembers the last cursor position delivered by a locator device. When a new 
data point comes from the mouse, or from the touchpad or bitpad in relative mode, a 
displacement is computed and applied to the last locator position. The 
TPAD _$SET_ CURSOR call makes the system forget the last locator position, and use 
the value passed in the call instead. The next locator data will then start from this new 
position instead of its former position. 

You will rarely need to make this call, as GPR and the display manager make the call at 
appropriate times. 

The origin is automatically re-established when you take your finger from the touchpad for 
more than one-eighth of a second. One effect of this is that the cursor typically doesn't 
move the next time you touch the pad in relative mode, unless you explicitly call 
TPAD _$SET_ CURSOR before that next touch. 

This call has meaning for relative and absolute/relative mode only. In absolute/relative 
mode, when you first touch the pad, the pad inputs coordinates in the absolute mode. To 
have effect, the call to TPAD _$SET_ CURSOR must occur after this first touch, but 
during the relative part of this use of the touchpad (that is, before you lift your finger for 
more than one-half second.) 
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TPAD _ $SET _MODE 

Sets the touch pad mode. 

FORMAT 

TPAD_$SET_MODE (mode, x-scale, y-scale, hysteresis, origin) 

INPUT PARAMETERS 

mode 

Cursor mode, in TPAD_$MODE_T format. This is a 2-byte integer. Specify one of the 
following predefined values: 

TPAD_$ABSOLUTE 
TPAD_$RELATIVE 
TPAD_$REL_ABS 

x- scale 

Scale factor in the x dimension. This is a 2-byte integer. 

y-scale 

Scale factor in the y dimension. This is a 2-byte integer. 

hysteresis 

Hysteresis factor, in pixels. This is a 2-byte integer. 

The hysteresis factor prevents the touchpad manager from responding to any minor 
movements you make unintentionally. This value defines a "box 1 * around your finger. The 
touchpad manager does not move the cursor if your finger stays within this box. 

If your finger moves beyond the box, the touchpad manager subtracts the hysteresis value 
from the distance moved, and moves the cursor the remaining distance. The default factor 
is 5. 

origin 

The point of origin for x and y in SMD_$POS_T format. This data type is 4 bytes long. 

OUTPUT PARAMETERS 

None. 

USAGE 

Use this call to set to mode, scale factors, and hysteresis factors of locator devices. You can 
also change the origin for relative or absolute/relative mode. This call applies to the 
touchpad, mouse, and bit pad locator devices. Note that the mouse uses only the scale and 
hysteresis factors and ignores the other mode settings, since it is an inherently relative 
device. 
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VEC 



The VEC (Vector Library) programming calls perform floating point and integer vector matrix 
arithmetic. This section describes their call syntax. The VEC calls do not use special data types 
or produce unique error messages. Refer to the Introduction at the beginning of this manual for a 
description of call syntax format. 

The majority of the calls in this section have four versions: single-precision floating-point, 
double-precision floating-point, 16-bit integer (INTEGER*2), and 32-bit integer (INTEGER*4). 
The names of all single-precision vector routines are in the form VEC_$Iname. Double-precision 
routines are named VEC_$Dname. 16-bit integer routines are named VEC_$Inamel6. 32-bit 
integer routines are named VEC_$Iname. For example, VEC_$DOT and VEC_$DDOT are 
single- and double-precision versions of DOT product routines. VEC_$IDOT and 
VEC_$IDOT16 are the 32-bit and 16-bit versions, respectively. 

Each type of routine generally requires parameters of the same type. For the double-precision 
routines, all floating-point parameters are double-precision; for the single-precision routines, all 
floating-point parameters must be single precision; for the integer procedures and functions, the 
parameters and returned values are integers, etc. 

Routine names that end in I denote "incremental" routines, which step through vectors at 
increments other than 1. 

When calling any of the vector routines, make sure that the indices you pass are valid. For best 
performance, these routines do not check index values for validity; hence, passing a value of zero 
can cause a variety of errors. 

NOTE: All matrices are assumed to be stored in FORTRAN (column-major) order. Because 
Pascal and C store matrix elements in row-major order, you may need to transpose or otherwise 
rearrange elements when calling vector routines from C or Pascal programs. 
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VEC_$ADD_ CONSTANT 

VEC _ $ADD _ CONSTANT 

Adds a constant to a vector. 

FORMAT 

VEC_$ADD_CONSTANT (start_vec, length, constant, result_vec) 
VEC_$DADD_CONSTANT (start_vec. length, constant, result_vec) 
VEC_$IADD_CONSTANT (start_vec. length, constant, result_vec) 
VEC_$IADD_C0NSTANT16 (start_vec, length, constant, result_vec) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector to which the value will be added. 

length 

Number of elements to add. This is a 4-byte integer. 

constant 

Value to be added to each element of start vec. 



OUTPUT PARAMETERS 

result _ vec 

Floating-point or integer vector containing the sum. 

USAGE 

These routines add a constant to a vector, returning the result in a second vector. The 
routines perform the following operation: 

DO 10 I + 1, LENGTH 

RESULT_VEC(I) = CONSTANT + START_VEC(I) 
10 CONTINUE 
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VEC_$ADD_CONSTANT_I 

VEC _ $ADD _ CONSTANT _ I 

Adds a constant to a vector, stepping through the vector by increments. 

FORMAT 

VEC_$ADD_CONSTANT_I (start_vec, incl, length, constant, result_vec, inc2) 
VEC_$DADD_CONSTANT_I (start_vec, incl, length, constant, result_vec, inc2) 
VEC_$IADD_CONSTANT_I (start_vec, incl, length, constant, result_vec, inc2) 
VEC_$IADD_C0NSTANT16_I(start_vec, incl, length, constant, result_vec, inc2) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector to which the value will be added. 

incl 

Increment for the index of start _vec. This is a 4-byte integer. 

length 

Number of elements to add. This is a 4-byte integer. 

constant 

Value to be added to each element of start _vec. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the sum. 

INPUT PARAMETERS 

inc2 

Increment for the index of result_vec. This is a 4-byte integer. 

USAGE 

These routines add a constant to a vector, stepping through their elements by user-specified 
increments. The routines perform the following operation: 

J=l 
K=l 
DO 10 I = 1, LENGTH 

RESULT_VEC (K) = CONSTANT+START_VEC(J) 

K = K+INC2 

J = J+INC1 
10 CONTINUE 
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VEC _ $ADD _ VECTOR 

VEC _ $ADD _ VECTOR 
Adds two vector. 

FORMAT 

VEC_$ADD_VECTOR (start_vec, add_vec, length, result_vec) 
VEC_$DADD_VECTOR (start_vec, add_vec, length, result_vec) 
VEC_$IADD_VECTOR (start_vec, add_vec, length, result_vec) 
VEC_$IADD_VECTOR16 (start_vec, add_vec, length, result_vec) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector to which the value will be added. 

add_vec 

Floating-point or integer vector to be added. 

length 

Number of elements to add. This is a 4-byte integer. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the sum. 

USAGE 

These routines add two vectors, returning the sum in a third vector. The routines perform 
the following operation: 

DO 10 I = 1, LENGTH 

RESULT_VEC(I) = START_VEC(I) + ADD_VEC(I) 
10 CONTINUE 
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VEC_$ADD_VECTOR_I 

Adds two vectors, stepping through them by increments. 

FORMAT 

VEC_$ADD_VECTOR_I(start_vec. incl. add_vec. inc2, length. result_vec. inc3) 
VEC_$DADD_VECTOR_I(start_vec, incl, add_vec. inc2, length, result_vec. 

inc3) 
VEC_$IADD_VECTOR_I(start_vec. incl, add_vec, inc2. length, result_vec. 

inc3) 
VEC_$IADD_VECT0R16_I(start_vec. incl, add_vec. inc2. length. result_vec. 

inc3) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector to which the value will be added. 

incl 

Increment for the index of start_vec. This is a 4-byte integer. 

add_vec 

Floating-point or integer vector to be added. 

inc2 

Increment for the index of add_vec. This is a 4-byte integer. 

length 

Length of the vector. This is a 4-byte integer. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the sum. 

INPUT PARAMETERS 

inc3 

Increment for the index of result _vec. This is a 4-byte integer. 
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USAGE 

These routines add two vectors, stepping through their elements by user-specified 
increments. The routines perform the following operation: 

J=l 
K=l 
DO 10 I = 1. LENGTH 

VEC3(J) = VEC1(K) + VEC2(L) 

J = J + INC3 

K = K + INC1 

L = L + INC2 
10 CONTINUE 
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VEC_$COPY 

Copies elements from one vector to another. 

FORMAT 

VEC_$COPY (start_vec. result_vec, length) 
VEC_$DCOPY (start_vec, result_vec, length) 
VEC_$ICOPY (start_vec, result_vec, length) 
VEC_$IC0PY16 (start_vec, result_vec, length) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector from which elements will be copied. 

length 

Number of elements to copy. This is a 4-byte integer. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector to which elements will be copied. 

USAGE 

These routines copy elements from one vector to another. The routines perform the 
following operation: 

DO 10 I = 1, LENGTH 

RESULT_VEC(I) = START_VEC(I) 
10 CONTINUE 
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YEC_$COPY_I 

Copies elements from one vector to another, stepping through the vectors by increments. 

FORMAT 

VEC_$COPY_I (vecl, incl, vec2, inc2, length) 
VEC_$DCOPY_I (vecl, incl, vec2, inc2, length) 
VEC_$ICOPY_I (vecl, incl, vec2, inc2. length) 
VEC_$IC0PY16_I (vecl, incl, vec2, inc2, length) 

INPUT PARAMETERS 

vecl 

Floating-point or integer vector from which elements will be copied. 

incl 

Increment for the index of vecl. This is a 4-byte integer. 

inc2 

Increment for the index of vec2. This is a 4-byte integer. 

length 

Number of elements to copy. This is a 4-byte integer. 

OUTPUT PARAMETERS 

vec2 

Floating-point or integer vector to which elements will be copied. 

USAGE 

These routines copy a vector but use an increment to step through the vector. 
VEC_$COPY_I moves 32 bits regardless of data type and VEC_$DCOPY_I moves 64 
bits. The routines perform the following operation: 

J = 1 
K = 1 
DO 10 I = 1, LENGTH 

VEC2(J) = VEC1(K) 

J = J+INC2 

K = K+INC1 
10 CONTINUE 
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VEC_$DOT 

VEC_$DOT 

Calculates the dot product of two vectors. 

FORMAT 

result = VEC_$DOT (vecl, vec2, length) 
result = VEC_$DDOT (vecl, vec2, length) 
result = VEC_$IDOT (vecl, vec2, length) 
result = VEC_$ID0T16 (vecl, vec2, length) 

RETURN VALUE 

result 

Floating-point or integer dot product. 

INPUT PARAMETERS 

vecl, vec2 

Floating-point or integer vectors. 

length 

Number of elements to add. This is a 4-byte integer. 

USAGE 

These routines calculate the dot product of two vectors. The routines perform the following 
operation: 

DO 10 I = 1, LENGTH 
TEMP = TEMP + VECl(I) * VEC2(I) 
10 CONTINUE 

VEC $D0T = TEMP 
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VEC_$DOT_I 

VEC_$DOT_I 

Calculates the dot product of two vectors, stepping through the vectors by increments. 

FORMAT 

result = VEC_$DOT_I (vecl, incl, vec2, inc2, length) 
result = VEC_$DDOT_I (vecl, incl, vec2, inc2, length) 
result = VEC_$IDOT_I (vecl, incl, vec2, inc2, length) 
resuit = VEC_$ID0T16_I (vecl, incl, vec2, inc2, length) 

RETURN VALUE 

result 

Floating-point or integer dot product. 

INPUT PARAMETERS 

vecl 

Floating-point or integer vector. 

incl 

Increment for the index of vecl. This is a 4-byte integer. 

vec2 

Floating-point or integer vector. 

inc2 

Increment for the index of vecl. This is a 4-byte integer. 

length 

Number of elements to add. This is a 4-byte integer. 

USAGE 

These routines calculate the dot product of two vectors, stepping through the vectors with a 
user-supplied increment. The routines perform the following operation: 

J = 1 
K = 1 
DO 10 I = 1, LENGTH 

TEMP - TEMP + VECl(J) * VEC2(K) 

J = J + INC1 

K = K + INC2 
10 CONTINUE 

VEC $D0T = TEMP 
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YEC_$DP_SP 

Copies a double-precision vector to a single precision vector. 

FORMAT 

VEC_$DP_SP (dp_vec, sp_vec, length) 

INPUT PARAMETERS 

dp_vec 

Floating-point double-precision vector. 

OUTPUT PARAMETERS 

sp_vec 

Floating-point single-precision resultant vector. 

INPUT PARAMETERS 

length 

Number of elements to copy. This is a 4-byte integer. 

USAGE 

VEC_$DP_SP copies a double-precision vector to a single-precision resultant vector. The 
routine performs the following operation: 

DO 10 1=1. LENGTH 

SP_VEC(I) = SNGL(DP_VEC(I)) 
10 CONTINUE 
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VEC $DP SP I 



Copies a double-precision vector to a single-precision vector, stepping through the vectors 
incrementally. 



FORMAT 

VEC_$DP_SP_I (dp_vec, incl, sp_vec. inc2, length) 

INPUT PARAMETERS 

dp_vec 

Double-precision floating-point vector. 

incl 

Increment for the index of dp _vec. This is a 4-byte integer. 

OUTPUT PARAMETERS 

sp__vec 

Single-precision floating-point resultant vector. 

INPUT PARAMETERS 

inc2 

Increment for the index of sp_vec. This is a 4-byte integer. 

length 

Number of elements to copy. This is a 4-byte integer. 

USAGE 

VEC_$DP_SP_I copies a double precision vector to a single precision resultant vector, 
stepping through the vectors by user-supplied increments. The routine performs the 
following operation: 

J=l 
K=l 
DO 10 1=1, LENGTH 

SP_VEC(K) = SNGL (DP_VEC(J)) 

J = J+INC1 

K = K+INC2 
10 CONTINUE 
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VEC_$INIT 

Initializes a vector with a constant. 

FORMAT 

VEC_$INIT (vector, length, constant) 
VEC_$DINIT (vector, length, constant) 
VEC_$IINIT (vector, length, constant) 
VEC_$IINIT16 (vector, length, constant) 

INPUT/OUTPUT PARAMETERS 

vector 

Upon input Floating-point or integer vector to be initialized. 

Upon output Floating-point or integer vector which has been initialized to a constant. 

INPUT PARAMETERS 

length 

Number of elements to initialize. This is a 4-byte integer. 

constant 

Floating-point or integer constant to be assigned to elements of vector. 

USAGE 

These routines perform the following operation: 

DO 10 I = 1, LENGTH 

VECTOR (I) = CONSTANT 
10 CONTINUE 
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VEC _ $MAT _MULT 

Multiplies two 4x4 matrices, returning the result in a 4 x 4 matrix. 

FORMAT 

VEC_$MAT_MULT (matrixl, matrix2. out_matrix) 
VEC_$DMAT_MULT (matrixl, matrix2, out_matrix) 
VEC_$IMAT_MULT (matrixl, matrix2, out_matrix) 
VEC_$IMAT_MULT16 (matrixl, matrix2, out_matrix) 

INPUT PARAMETERS 

matrixl 

A 4 x 4 floating-point or integer matrix to be multiplied. 

matrix2 

A 4 x 4 floating-point or integer matrix to be multiplied. 

OUTPUT PARAMETERS 

out _ matrix 

Floating-point or integer matrix containing the product. 

USAGE 

These routines multiply two 4x4 matrices, returning the result as a third 4x4 matrix. 
They are intended for use in graphics applications, and perform the following operation: 

DO 10 J = 1,4 
DO 10 I = 1.4 

CALL VEC_$P0ST_MULT (MATRIX1 , MATRIX2 ( J, I) , 0UT_MATRIX( J, I) ) 
10 CONTINUE 
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VEC_$MAT_MULTN 

Multiplies two variably-dimensioned matrices, returning the result in a third matrix. 

FORMAT 

VEC_$MAT_MULTN (matrixl, matrix2, m, n, s, out_matrix) 
VEC_$DMAT_MULTN (matrixl. matrix2, m, n, s. outjnatrix) 
VEC_$IMAT_MULTN (matrixl, matrix2, m, n, s, out_matrix) 
VEC_$IMAT_MULTN16 (matrixl, matrix2, m. n, s, out_matrix) 

INPUT PARAMETERS 

matrixl 

First floating-point or integer matrix of dimensions m x n to be multiplied. 

matrix2 

Second floating-point or integer matrix of dimensions n x s to be multiplied. 

m, n, s 

The various matrix dimensions. These are 4-byte integers. 

OUTPUT PARAMETERS 

out _ matrix 

Floating-point or integer matrix of dimensions m x s containing the product. 

USAGE 

These routines multiply two matrices with dimensions specified by you, returning the result 
as a third matrix. Note that the matrices are assumed to be stored in FORTRAN 
(column-major) order. These routines perform the following operation: 

DO 10 I = 1,M 
DO 10 J = 1,S 

0UT_MATRIX(I. J) =0.0 

DO 10 K = l.N 

0UT_MATRIX(I, J) = 0UT_MATRIX(I, J) + MATRIX1(I,K) * MATRIX2(K,J) 
10 CONTINUE 
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VEC_$MAX 

Finds the element with the greatest maximum absolute value in a vector and returns its 
value and location. 

FORMAT 

VEC_$MAX (start_vec, length, result, result_loc) 
VEC_$DMAX (start_vec. length, result, result_loc) 
VEC_$IMAX (start_vec, length, result, result_loc) 
VEC_$IMAX16 (start_vec, length, result, result_loc) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector to be searched. 

length ( 

Number of elements to examine. This is a 4-byte integer. v. 

OUTPUT PARAMETERS 

result 

Floating-point or integer maximum absolute value of all the elements searched. 

result _loc 

Location of value within the vector. This is a 4-byte integer. 

USAGE 

These routines search through a vector and return the maximum absolute value found and 
its location within the vector. The routines perform the following: 

RESULT = ABS (START_VEC(1) ) 
RESULT_LOC = 1 
DO 10 1=2, LENGTH 

IF (ABS (START_VEC( I) ) . GT . RESULT) THEN 
RESULT_LOC = I 
RESULT = ABS(START_VEC(I)) 
END IF 
10 CONTINUE 
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VEO_$MAX_I 

( j Searches a vector for the maximum absolute value, stepping through the vector by 

^-^ increments greater than 1. 

FORMAT 

VEC_$MAX_I (start_vec, inc, length, result. result_loc) 
VEC_$DMAX_I (start_vec, inc, length, result, result_loc) 
VEC_$IMAX_I (start_vec, inc, length, result, result_loc) 
VEC_$IMAX16_I (start_vec, inc, length, result, result_loc) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector to be searched. 

inc 

( ] Increment used to step through the start_vec. This is a 4-byte integer. 

length 

Number of elements to examine. This is a 4-byte integer. 

OUTPUT PARAMETERS 

result 

Floating-point or integer maximum absolute value of all the elements searched. 

result _loc 

Location of value within given vector. This is a 4-byte integer. 

USAGE 

These routines search through a vector by a positive increment and return the greatest 
absolute value found and its location within the vector. The routines perform the following: 

RESULT = ABS(START_VEC(1)) 

RESULTJLOC = 1 

J = 1+INC1 

DO 10 1=2, LENGTH 

IF (ABS (START_VEC ( J) ) . G . T . RESULT) THEN 
RESULT_L0C = I 
RESULT = ABS(START_VEC(J)) 
END IF 
J = J+INC1 
10 CONTINUE 
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VEC_$MULT_ADD 

VEC_$MULT_ADD 

Multiplies a vector by a constant and adds the result to a second vector. 

FORMAT 

VEC_$MULT_ADD (add_vec, mult_vec, length, constant, result_vec) 
VEC_$DMULT_ADD (add_vec, mult_vec, length, constant, result_vec) 
VEC_$IMULT_ADD (add_vec, mult_vec, length, constant, result_vec) 
VEC_$IMULT_ADD16 (add_vec, mult_vec, length, constant, result_vec) 

INPUT PARAMETERS 

add_vec 

Floating-point or integer vector to be added. 

mult_vec 

Floating-point or integer vector to be multiplied by the constant. 

length 

Number of elements to add. This is a 4-byte integer. 

constant 

Floating-point or integer constant to be multiplied by mult_vec. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the sum. 

USAGE 

These routines multiply one vector (input as mult_vec) by a constant, and add the result 
to a second vector (input as add__vec). The result is returned in a third vector. The 
routines perform the following operation: 

DO 10 I = 1, LENGTH 

RESULT_VEC(I) = ADD_VEC(I) + CONSTANT*MULT_VEC(l) 
10 CONTINUE 
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VEC_$MULT_ADD_I 

Multiplies a vector by a constant and adds the result to a second vector, stepping through 
both vectors and the result by increments. 

FORMAT 

VEC_$MULT_ADD_I (add_vec, incl, mult_vec. inc2, 

length, constant. result_vec, inc3) 
VEC_$DMULT_ADD_I (add_vec. incl. mult_vec. inc2. 

length, constant. result_vec. inc3) 
VEC_$IMULT_ADD_I (add_vec. incl. mult_vec. inc2. 

length, constant. result_vec. inc3) 
VEC_$IMULT_ADD16_I (add_vec. incl. multjvec. inc2. 

length, constant, result vec. inc3) 



INPUT PARAMETERS 

add _ vec 

Floating-point or integer vector to be added. 

incl 

Increment for the index of add_vec. This is a 4-byte integer. 

mult _ vec 

Floating-point or integer vector to be multiplied by the constant. 

inc2 

Increment for the index of mult _ vec. This is a 4-byte integer. 

length 

Number of elements on which to operate. This is a 4-byte integer. 

constant 

Floating-point or integer constant to be multiplied by mult__vec2. 

OUTPUT PARAMETERS 

result _ vec 

Floating-point or integer vector containing the sum. 

INPUT PARAMETERS 

inc3 

Increment for the index of result _ vec. This is a 4-byte integer. 
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USAGE 

These routines multiply one vector by a constant and add the result to a second vector. The 
result is returned in a third vector. The indices to all three vectors are incremented by 
user-specified values. The routines perform the following operation: 

J = 1 

K = 1 
L = 1 
DO 10 I = 1, LENGTH 

RESULT (J) = ADD_VEC(K) + CONSTANT*MULT_VEC (L) 

J = J + INC3 

K = K + INC1 

L = L + INC2 
10 CONTINUE 
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VEC_$MULT_CONSTANT 

VEC _ $MULT _ CONSTANT 

Multiplies a vector by a scalar constant and returns the result in a second vector. 

FORMAT 

VEC_$MULT_CONSTANT (mult_vec, length, constant, result_vec) 
VEC_$DMULT_CONSTANT (mult_vec, length, constant, result_vec) 
VEC_$IMULT_CONSTANT (mult_vec, length, constant, result_vec) 
VEC_$IMULT_C0NSTANT16 (mult_vec, length, constant, result_vec) 

INPUT PARAMETERS 

mult_vec 

Floating-point or integer vector to be multiplied. 

length 

Number of elements to multiply. This is a 4-byte integer. 

constant 

Floating-point or integer constant to multiply by mult_vec. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the product. 

USAGE 

These routines multiply one vector by a scalar constant, returning the result in a second 
vector. The routines perform the following operation: 

DO 10 I = 1, LENGTH 

RESULT_VEC(I) = CONSTANT * MULT_VEC(I) 
10 CONTINUE 
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YEC _ $MULT _ CONSTANT _ I 

Multiplies a vector by a scalar constant, returns the result in a second vector, and steps 
through the vectors by increments. 

FORMAT 

VEC_$MULT_CONSTANT_I (mult_vec, incl, length, constant, result_vec. inc2) 
VEC_$DMULT_CONSTANT_I (mult_vec. incl, length, constant, result_vec. inc2) 
VEC_$IMULT_CONSTANT_I (mult_vec. incl, length, constant, result_vec, inc2) 
VEC_$IMULT_C0NSTANT16_I(mult_vec, incl, length, constant, result_vec, inc2) 

INPUT PARAMETERS 

mult_vec 

Floating-point or integer vector from which data will be copied. 

incl 

Increment for the index of mult_vec. This is a 4-byte integer. 

length 

Number of elements on which to operate. This is a 4-byte integer. 

constant 

Floating-point or integer constant to multiply by mult_vec. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the result. 

INPUT PARAMETERS 

inc2 

Increment for the index of result _vec. This is a 4-byte integer. 

USAGE 

These routines multiply elements of a vector by a scalar constant and store the result in a 
second vector. The routines step through both vectors by increments. The routines 
perform the following: 

J = 1 
K = 1 
DO 10 1=1. LENGTH 

RESULT (J) = MULT_VEC(K) * CONSTANT 

J = J+INC2 

K = K+INC1 
10 CONTINUE 
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VEC $POSTMULT 



OPostmultiplies a 4 x 4 matrix by a 4 x 1 column vector, returning the result in a second 



vector. 



FORMAT 

VEC_$POSTMULT (matrix, col_vec, result_vec) 
VEC_$DPOSTMULT (matrix. col_vec, result_vec) 
VEC_$IPOSTMULT (matrix, col_vec, result_vec) 
VEC_$IP0STMULT16 (matrix, col_vec. result_vec) 

INPUT PARAMETERS 

matrix 

A 4 x 4 floating-point or integer matrix to be postmultjplied. 

col_vec 

A 4 x 1 floating-point or integer column vector. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the product. 

USAGE 

These routines postmultiply a 4 x 4 matrix by a 4 x 1 column vector, and return a 4 x 1 
column vector. They are intended for use in graphics applications, and perform the 
following operation: 

DO 10 J = 1,4 

RESULT_VEC(J) =0.0 
DO 10 I = 1,4 

RESULT_VEC(J) = RESULT_VEC ( J) + C0L_VEC(I) *MATRIX( J, I) 
10 CONTINUE 
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VEC $POSTMULTN 



Postmultiplies a variably-dimensioned matrix by an n x 1 vector, returning the result in a 
second vector. 



FORMAT 

VEC_$POSTMULTN (matrix, col_vec. m. n, result_vec) 
VEC_$DPOSTMULTN (matrix. col_vec. m. n. result_vec) 
VEC_$IPPSTMULTN (matrix. col_vec. m. n, result_vec) 
VEC $IP0STMULTN16 (matrix, col vec, m. n. result vec) 



INPUT PARAMETERS 

matrix 

An m x n floating-point or integer matrix to be postmultiplied. 

col _ vec 

An n x 1 floating-point or integer column vector. 

m, n 

Dimensions, of the matrices. These are 4-byte integers. 



OUTPUT PARAMETERS 

result _ vec 

An m x 1 floating-point or integer vector containing the product. 

USAGE 

These routines postmultiply a m x n matrix by a n x 1 column vector, and return an m x 1 
column vector. They perform the following operation: 

DO 10 I = l.M 

RESULT_VEC(I) =0.0 
DO 10 J = l.N 

RESULT_VEC(I) = RESULT_VEC(I) + C0L_VEC(J) * MATRIX (I. J) 
10 CONTINUE 
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VEC_$PREMULT 

Premultiplies a 4 x 4 matrix by a 1 x 4 row vector, returning the result in a second vector. 

FORMAT 

VEC_$PREMULT (row_vec, matrix, result_vec) 
VEC_$DPREMULT (row_vec, matrix, result_vec) 
VEC_$IPREMULT (row_vec, matrix, result_vec) 
VEC_$IPREMULT16 (row_vec, matrix, result_vec) 

INPUT PARAMETERS 

row_vec 

A 1 x 4 floating-point or integer row vector. 

matrix 

A 4 x 4 floating-point or integer matrix to be premultiplied. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the product. 

USAGE 

These routines premultiply a 4 x 4 matrix by a 1 x 4 row vector, and return a 1 x 4 row 
vector. They perform the following operation: 

DO 10 I = 1,4 

RESULT_VEC(I) =0.0 
DO 10 J = 1,4 

RESULT_VEC(I) = RESULTJ/EC (I) + R0W_VEC(J) * MATRIX (J, I) 
10 CONTINUE 
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VEC $PREMULTN 



Premultiplies a variably-dimensioned matrix by a 1 x n row vector, returning the result in a 
second vector. 



FORMAT 

VEC_$PREMULTN (row_vec. matrix, m. n. result_vec) 
VEC_$DPREMULTN (row_vec. matrix, m. n, result_vec) 
VEC_$IPREMULTN (row_vec. matrix, m. n. result_vec) 
VEC_$IPREMULTN16 (row_vec. matrix, m. n. result_vec) 

INPUT PARAMETERS 

row_vec 

A 1 x m floating-point or integer row vector. 

matrix 

An m x n floating-point or integer matrix to be premultiplied. 

m, n 

Dimensions of the matrices. These are 4-byte integers. 

OUTPUT PARAMETERS 

result __vec 

One by n floating-point or integer vector containing the product. 

USAGE 

These routines premultiply a variably-dimensioned matrix by a 1 x m row vector, and 
return a 1 x n row vector. They perform the following operation: 

DO 10 I = l.N 

RESULT_VEC(I) =0.0 
DO 10 J = l.M 

RESULT_VEC(I) = RESULT_VEC ( I ) + R0W_VEC(J) * MATRIX(J.I) 
10 CONTINUE 



VEC VEC- 26 



VEC $SP DP 



VEC_$SP_DP 

Copies a single-precision vector to a double-precision vector. 

FORMAT 

VEC_$SP_DP (sp_vec, dp_vec, length) 

INPUT PARAMETERS 

sp_vec 

Single-precision floating-point vector. 

OUTPUT PARAMETERS 

dp_vec 

Double-precision floating-point resultant vector. 

INPUT PARAMETERS 

length 

Number of elements to copy. This is a 4-byte integer. 



USAGE 

OVEC_$SP_DP copies a single-precision vector to a double-precision resultant vector. The 
ron tin p nprfnrms t.hp f n\ 1 rvwi n cr • 



routine performs the following: 

DO 10 1=1. LENGTH 

DP_VEC(I) = DBLE (SP_VEC(I)) 
10 CONTINUE 
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YEC $SP DP I 



Copies a single-precision vector to a double-precision vector, stepping through the vectors 
incrementally. 



FORMAT 

VEC_$SP_DP_I (sp_vec. incl. dp_vec. inc2, length) 

INPUT PARAMETERS 

sp_vec 

Floating-point, single-precision vector. 

incl 

Increment for the index of sp_vec. This is a 4-byte integer. 

OUTPUT PARAMETERS 

dp_vec 

Floating-point double-precision resultant vector. 

inc2 

Increment for the index of dp_vec. This is a 4-byte integer. 

INPUT PARAMETERS 

length 

Number of elements to copy. This is a 4-byte integer. 

USAGE 

VEC_$SP_DP_I copies a single-precision vector to a double-precision resultant vector, 
stepping through the vectors by user-supplied increments. It does the following: 

J = 1 
K = 1 
DO 10 1=1. LENGTH 

DP_VEC(K) = DBLE (SP_VEC(J)) 

J = J+INC1 

K = K+INC2 
10 CONTINUE 
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VEO_$SUB 

Subtracts one vector from another. 

FORMAT 

VEC_$SUB (start_vec, sub_vec, length, result_vec) 
VEC_$DSUB (start_vec, sub_vec, length, result_vec) 
VEC_$ISUB (start_vec, sub_vec, length, result_vec) 
VEC_$ISUB16 (start_vec, sub_vec, length, result_vec) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector from which the values will be subtracted. 

sub_vec 

Floating-point or integer vector to be subtracted. 

length 

Number of elements to subtract. This is a 4-byte integer. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the difference. 

USAGE 

These routines subtract one vector from another, returning the result in a third vector. The 
routines perform the following operation: 

DO 10 I = 1, LENGTH 
RESULT_VEC(I) = START_VEC(I) - SUB_VEC(I) 
10 CONTINUE 
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YEC_$SUB_I 

Subtracts one vector from another, stepping through the vectors by increments. 

FORMAT 

VEC_$SUB_I (start_vec. incl, sub_vec, inc2, length, result_vec, inc3) 
VEC_$DSUB_I (start_vec, incl. sub_vec, inc2, length, result_vec, inc3) 
VEC_$ISUB_I (start_vec, incl, sub_vec, inc2, length, result_vec, inc3) 
VEC_$ISUB16_I (start_vec, incl, sub_yec, inc2, length, result_vec, inc3) 

INPUT PARAMETERS 

start _vec 

Floating-point or integer vector from which the values will be subtracted. 

incl 

Increment for the index of start _vec. This is a 4-byte integer. 

sub_vec 

Floating-point or integer vector to be subtracted. 

inc2 

Increment for the index of sub_vec. This is a 4-byte integer. 

length 

Number of elements to subtract . This is a 4-byte integer. 

OUTPUT PARAMETERS 

result _vec 

Floating-point or integer vector containing the difference. 

INPUT PARAMETERS 

inc3 

Increment for the index of result_vec. This is a 4-byte integer. 

USAGE 

These routines subtract one vector from another, returning the result in a third vector. The 
indices to all three vectors are incremented by user-specified values. The routines perform 
the following operation: 

DO 10 I = 1, LENGTH 

RESULT_VEC(J) = START_VEC(K) - SUB_VEC(L) 
J = J + INC3 
K = K + INC1 
L = L + INC2 
10 CONTINUE 
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VEC_$SUM 

Sums the elements of a vector. 

FORMAT 

sum = VEC_$SUM (vec, length) 
sum = VEC_$DSUM (vec, length) 
sum = VEC_$ISUM (vec, length) 
sum = VEC_$ISUM16 (vec, length) 

RETURN VALUE 

sum 

Floating-point or integer sum of first "length" elements of vec. 

INPUT PARAMETERS 

vec 

Floating-point or integer vector to be summed. 

length 

Number of elements to sum. This is a 4-byte integer. 

USAGE 

These routines sum the elements of a vector. The routines perform the following operation: 

DO 10 I = 1. LENGTH 
SUM = SUM + VEC (I) 
10 CONTINUE 
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VEC_SUM_I 

Sums the elements of a vector, stepping through the vector by increments. 

FORMAT 

sum = VEC_$SUM_I (vec. inc. length) 
sum = VEC_$DSUM_I (vec. inc, length) 
sum = VEC_$ISUM_I (vec, inc. length) 
sum = VEC_$ISUM16_I (vec. inc, length) 

RETURN VALUE 

sum 

Floating-point or integer sum of the elements. 



INPUT PARAMETERS 

vec 

Floating-point or integer vector to be summed. 

inc 

Increment for the index of vec. This is a 4-byte integer. 

length 

Number of elements to sum. This is a 4-byte integer. 



USAGE 

These functions step through a vector incrementally, summing its elements. The sum is 
returned as the value of the function. The routines do the following: 

J = 1 

SUM =0.0 

DO 10 1=1. LENGTH 

SUM = SUM+VEC(J) 

J = J+INC1 
10 CONTINUE 
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VEC_$SWAP 

Swaps the elements of two vectors. 

FORMAT 

VEC_$SWAP (vecl, vec2, length) 
VEC_$DSWAP (vecl. vec2. length) 
VEC_$ISWAP (vecl, vec2. length) 
VEC_$ISWAP16 (vecl. vec2. length) 

INPUT/OUTPUT PARAMETERS 

vecl, vec2 

Floating-point or integer vectors to be swapped. 

INPUT PARAMETERS 

length 

Number of elements to swap. This is a 4-byte integer. 

USAGE 

These routines swap the elements of two vectors. They perform the following operation: 

DO 10 I = 1. LENGTH 
TEMP = VEC1(I) 
VECl(I) = VEC2(I) 
VEC2(I) = TEMP 
10 CONTINUE 
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VEC_$SWAP_I 

Swaps the elements of two vectors, stepping through the vectors by increments. 

FORMAT 

VEC_$SWAP_I (vecl, incl, vec2, inc2, length) 
VEC_$DSWAP_I (vecl, incl, vec2, inc2. length) 
VEC_$ISWAP_I (vecl, incl, vec2, inc2, length) 
VEC_$ISWAP16_I (vecl, incl, vec2, inc2, length) 

INPUT/OUTPUT PARAMETERS 

vecl 

Floating-point or integer vector to be swapped. 

INPUT PARAMETERS 

incl 

Increment for the index of vecl. This is a 4-byte integer. 

INPUT/ OUTPUT PARAMETERS 

vec2 

Floating-point or integer vector to be swapped. 

INPUT PARAMETERS 

inc2 

Increment for the index of vec2. This is a 4-byte integer. 

length 

Number of elements to swap. This is a 4-byte integer. 

USAGE 

These routines step through two vectors by increments, swapping their elements. They 
perform the following operation: 

J = 1 
K = 1 
DO 10 1=1, N 

TEMP = VEC1(J) 

VEC1(J) = VEC2(K) 

VEC2(K) = TEMP 

J = J + INC1 

K = K + INC2 
10 CONTINUE 
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VEC_$ZERO 

Zeros a vector. 

FORMAT 

VEC_$ZERO (vector, length) 
VEC_$DZERO (vector, length) 
VEC_$IZERO (vector, length) 
VEC_$IZER016 (vector, length) 

INPUT/OUTPUT PARAMETERS 

vector 

Floating-point or integer vector to be zeroed. 

INPUT PARAMETERS 

length 

Number of elements to zero. This is a 4-byte integer. 

USAGE 

These routines zero the elements of a vector. They perform the following operation: 

DO 10 I = 1. LENGTH 
VEC(I) = 0.0 
10 CONTINUE 
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VEC_$ZERO_I 

Zeros a vector by increments. 

FORMAT 

VEC_$ZERO_I (vector, inc. length) 
VEC_$DZERO_I (vector, inc. length) 
VEC_$IZERO_I (vector, inc. length) 
VEC_$IZER016_I (vector, inc. length) 

INPUT/OUTPUT PARAMETERS 

vector 

Floating-point or integer vector to be zeroed. 

INPUT PARAMETERS 

inc 

Increment for the index of vector. This is a 4-byte integer. 

length 

Number of elements to zero. This is a 4-byte integer. 

USAGE 

These routines step through a vector by increments, zeroing its elements. VEC_$ZERO__I 
zeros 32 bits regardless of data type and VEC_$DZERO__I zeros 64 bits. The routines 
perform the following: 

J = 1 

DO 10 1=1. LENGTH 
VEC(J) =0.0 
J = J+INC1 
10 CONTINUE 
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The VFMT (Variable Text Format) programming calls convert program data from one format to 
another. This section describes their data types, call syntax, and error codes. Refer to the 
Introduction at the beginning of this manual for a description of data-type diagrams and call 
syntax format. 
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DATA TYPES 



STATUS $T 



A status code. The diagram below illustrates the 
STATUS _$T data type: 



byte: 
offset 



field name 



31 



0: 


integer 


all 


0: 


" 31 


or 





fail 






24 




subsys 


1: 




16 


mode 


2: 


integer 


code 



Field Description: 

all 

All 32 bits in the status code. 

fail 

The fail bit. If this bit is set, the error was not 
within the scope of the module invoked, but 
occurred within a lower-level module (bit 31). 

subsys 

The subsystem that encountered the error (bits 

24 - 30). 
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mode 

The module that encountered the error (bits 16 - 

23). 

code 

A signed number that identifies the type of error 

that occurred (bits - 15). 

An array of up to 200 characters. Access control 
string. 
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VFMT_$DECODE 

Decodes data from a text buffer and writes the decoded data into program variables. 

FORMAT 

return-value = VFMT_$DEC0DE{2 1 5 1 10} (control-string, text-buffer, size, 

count, status, al, a2, ... alO) 

RETURN VALUE 

return-value 

Position in the text buffer of the last decoded character. This is a 2-byte integer. 

The return-value indicates the position in the text buffer of the last decoded character. The 
first buffer position is 1. 

INPUT PARAMETERS 

control-string 

Character string giving instructions for decoding the input data. See the VFMT chapter of 
the Programming With General System Calls manual for details about how to construct 
control strings. 

text- buffer 

Buffer containing data to be decoded, in VFMT_$STRING_T format. This is an array of 
up to 200 characters. 

size 

Number of bytes of data in the text buffer. This is a 2-byte integer. 

OUTPUT PARAMETERS 

count 

Number of fields successfully decoded. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the VFMT 
Data Types section for more information. 

INPUT/OUTPUT PARAMETERS 

al, a2, ... alO 

Up to ten variables containing decoded data The number required depends on the number 
immediately following VFMT_$DECODE. The number of variables cannot exceed this 
number. In Pascal programs, you must specify exactly this number of variables, using 
dummy variables if necessary. 

If you are decoding ASCII text strings, you must provide two variables for each text string: 
a character string to contain the decoded string, and a 2-byte integer variable to contain the 
length of the decoded string, which is returned by VFMT. 
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VFMT_$DECODE 

The returned length of the output string depends on what you specify in the control string. 
VFMT determines the output string length using the M directive or, if M is omitted, using 
the previous value of the string length variable. In the latter way you may use this integer 
variable to input a maximum string length. 

If you specify a maximum string length with the M directive, and the length of the string 
decodes is less than the maximum, VFMT returns the actual length (the lesser value) in the 
string-length variable. 

USAGE 

This is actually a description of three separate DOMAIN system calls: VFMT_$DECODE2, 
VFMT_$DECODE5, and VFMT_$DECODE10. The number immediately following 
VFMT_$DECODE indicates the maximum number of variables the call can handle. The 
number must follow immediately, with no embedded spaces. 
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VFMT_$ENCODE 

Encodes and writes data into a text buffer. 

FORMAT 

VFMT_$ENCODE [2 1 5 1 10] (control-string, text-buffer, capacity, size, 

al , a2 , ... a20) 

INPUT PARAMETERS 

control- string 

Character string giving instructions for encoding the output data. See the VFMT chapter 
of the Programming With General System Calls manual for details about how to construct 
control strings. 

OUTPUT PARAMETERS 

text- buffer 

Buffer to contain the encoded data, in VFMT _$ STRING _T format. This is an array of 
up to 200 characters. 

INPUT PARAMETERS 

capacity 

Maximum number of characters that may be placed in the text-buffer. This is a 2-byte 
integer. 

OUTPUT PARAMETERS 

size 

Number of characters placed in the buffer. This is a 2-byte integer. 

INPUT PARAMETERS 

al, a2 , ... a20 

Up to twenty variables containing data for encoding. The number of arguments required 
depends on the number immediately following VFMT_$ENCODE, if any (see Usage 
description below). If you append a number to the call, then the number of variables 
cannot exceed this number. In Pascal programs, you must specify exactly this number of 
variables, using dummy variables if necessary. 

If you are encoding ASCII text strings, you must provide two variables for each text string: 
a character string containing the string, and a 2-byte integer variable containing the length 
of the string. 

USAGE 

This is actually a description of four separate DOMAIN system calls: VFMT_$ENCODE, 
VFMT_$ENCODE2, VFMT_$ENCODE5, and VFMT _$ENCODE10. The number 
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VFMT $ENCODE 



immediately following VFMT_$ENCODE (if any) indicates the maximum number of 
variables the call can handle. The number must follow immediately, with no embedded 
spaces. If no number is specified, you may use a variable number of arguments up to a 
maximum of 20. 

Any individual YFMT_$ENCODE[2|5|10] call can write out a maximum of 512 bytes per 
call. If you attempt to write more than that limit, it is truncated. 
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VFMT_$READ 

VFMT_$READ 

Reads character data from standard input and decodes them into variables. 

FORMAT 

VFMT_$READ{2 1 5 1 10} (control-string, count, status, al , a2, ... alO) 

INPUT PARAMETERS 

control- string 

A character string giving instructions for decoding the input data. See the VFMT chapter 
of the Programming With General System Calls manual for details about how to construct 
control strings. 

OUTPUT PARAMETERS 

count 

Number of fields successfully decoded. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the VFMT 
Data Types section for more information. 

INPUT/OUTPUT PARAMETERS 

al, a2, ... alO 

Up to ten variables containing decoded data. The number required depends on the number 
immediately following VFMT_$READ. The number of variables cannot exceed this 
number. In Pascal programs, you must specify exactly this number of variables, using 
dummy variables if necessary. 

If you are decoding ASCII text strings, you must provide two variables for each text string: 
a character string to contain the decoded string, and a 2-byte integer variable to contain the 
length of the decoded string, which is returned by VFMT. 

The returned length of the output string depends on what you specify in the control string. 
VFMT determines the output string length using the M directive or, if M is omitted, using 
the previous value of the string length variable. In the latter way you may use this integer 
variable to input a maximum string length. 

If you specify a maximum string length with the M directive, and the length of the string 
decodes is less than the maximum, VFMT returns the actual length (the lesser value) in the 
string-length variable. 

USAGE 

This is actually a description of three separate DOMAIN system calls: VFMT_$READ2, 
VFMT_$READ5, and VFMT_$READ10. The number immediately following 
VFMT_$READ indicates the maximum number of variables the call can handle. The 
number must follow immediately, with no embedded spaces. 
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VFMT_$RS r- 

i 

Reads character data from a stream and decodes them into variables. V. 

FORMAT 

VFMT_$RS{2 | 5 | 10} (stream-id, control-string, count, status, al, a2, . . . alO) 

INPUT PARAMETERS 

stream- id 

Number of the stream from which data are read, in STREAM_$ID_T format. This is a 
2-byte integer. 

control- string 

A character string giving instructions for decoding the input data. See the VFMT chapter 

of the Programming With General System Calls manual for details about how to construct 

control strings. f 

OUTPUT PARAMETERS 

count 

Number of fields successfully decoded. This is a 2-byte integer. 

status 

Completion status, in STATUS _$T format. This data type is 4 bytes long. See the VFMT f 

Data Types section for more information. 



INPUT/OUTPUT PARAMETERS 

al, a2, ... alO 

Up to ten variables containing decoded data. The number required depends on the number 
immediately following VFMT_$RS. The number of variables cannot exceed this number. 
In Pascal programs, you must specify exactly this number of variables, using dummy 
variables if necessary. 

If you are decoding ASCII text strings, you must provide two variables for each text string: 
a character string to contain the decoded string, and a 2-byte integer variable to contain the 
length of the decoded string, which is returned by VFMT. 

The returned length of the output string depends on what you specify in the control string. 
VFMT determines the output string length using the M directive or, if M is omitted, using 
the previous value of the string length variable. In the latter way you may use this integer 
variable to input a maximum string length. 

If you specify a maximum string length with the M directive, and the length of the string 
decoded is less than the maximum, VFMT returns the actual length (the lesser value) in the 
string-length variable. 

USAGE 

This is actually a description of three separate DOMAIN system calls: VFMT_$RS2, 
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^. VFMT_$RS5, and VFMT_$RS10. The number immediately following VFMT_$RS 

( j indicates the maximum number of variables the call can handle. The number must follow 
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immediately, with no embedded spaces. 



O 
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VFMT_$ WRITE 

VFMT_$ WRITE 

Encodes data and writes them to standard output. 

r 

FORMAT 

VFMT_$WRITE[2|5|10] (control-string, al, a2 , ... a20) 

INPUT PARAMETERS 

control- string 

A character string containing the control information for encoding. See the VFMT chapter 
of the Programming With General System Calls manual for details about how to construct 
control strings. 

al, a2 , ... a20 

Up to twenty variables containing data for encoding. The number of arguments required 
depends on the number immediately following VFMT_$WRITE, if any (see Usage 
description below). If you append a number to the call, then the number of variables 
cannot exceed this number. In Pascal programs, you must specify exactly this number of 
variables, using dummy variables if necessary. 

If you are encoding ASCII text strings, you must provide two variables for each text string: 
a character string containing the string, and a 2-byte integer variable containing the length 
of the string. 

USAGE 

This is actually a description of four separate DOMAIN system calls: VFMT_$WRITE, 
VFMT_$WRITE2, VFMT_$WRITE5, and VFMT_$WRITE10. The number 
immediately following VFMT_$WRITE (if any) indicates the maximum number of 
variables the call can handle. The number must follow immediately, with no embedded 
spaces. If no number is specified, you may use a variable number of arguments up to a 
maximum of 20. 

Any individual VFMT_$WRITE[2|5|10] call can write out a maximum of 512 bytes per 
call. If you attempt to write more than that, it is truncated. 
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VFMT_$WS 

Encodes data and writes them to a stream. 

FORMAT 

VFMT_$WS [2 | 5 | 10] (stream-id, control-string, al, a2 . ... a20) 

INPUT PARAMETERS 

stream- id 

The number of the stream to which data are written, in STREAM_$ID_T format. This 
is a 2-byte integer. 

control- string 

A character string containing the control information for encoding. See the VFMT chapter 
of the Programming With General System Calls manual for details about how to construct 
control strings. 

al, a2 , ... a20 

Up to twenty variables containing data for encoding. The number of arguments required 
depends on the number immediately following VFMT_$WS, if any (see Usage description 
below). If you append a number to the call, then the number of variables cannot exceed 
this number. In Pascal programs, if you append a number to the call, then you must 
specify exactly this number of variables, using dummy variables if necessary. 

If you are encoding ASCII text strings, you must provide two variables for each text string: 
a character string containing the string, and a 2-byte integer variable containing the length 
of the string. 

USAGE 

This is actually a description of four separate DOMAIN system calls: VFMT_$WS, 
VFMT_$WS2, VFMT_$WS5, and VFMT_$WS10. The number immediately following 
VFMT_$WS (if any) indicates the maximum number of variables the call can handle. The 
number must follow immediately, with no embedded spaces. If no number is specified, you 
may use a variable number of arguments up to a maximum of 20. 

Any individual VFMT_$WS[2|5|10] call can write out a maximum of 512 bytes per call. 
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ERRORS ^ 

VFMT _ $UNTERMINATED _ CTL _ STRING 
Unterminated control string. 

VFMT _ $INVALED _ CTL _ STRING 
Invalid control string. 

VFMT_$TOO_FEW_ARGS 

Too few arguments supplied for read/decode. 

VFMT _ $F W _ REQUIRED 

Field width missing on "(" designator. 

VFMT_$EOS 

Encountered end of string where more text was expected. 

VFMT _ $NULL _ TOKEN 

Encountered null token where numeric token was expected. /' 

VFMT _ $NONNUMERIC _ CHAR 

Non-numeric character found where numeric was expected. 

VFMT_$SIGN_NOT_ALLOWED 

Sign encountered in unsigned field. 

VFMT_ $VALUE_ TOO _LARGE 

Value out of range in text string. 

VFMT _ $NONMATCHING _ CHAR ( 

Character in text string does not match control string. v 

VFMT_$NONMATCHING_DELIMITER 

Terminator in text string does not match specified terminator. 

STATUS _$OK 

Successful completion. 
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